Skip to main content
Service accounts are machine users for server-to-server communication. Unlike human users who authenticate with passkeys, service accounts use a keypair to sign API requests.

​
When to use a service account

Use a service account when you need to:
  • Call the Dfns API from your backend server
  • Run automated processes (scheduled transfers, batch operations)
  • Build applications that create wallets or manage users on behalf of your organization

​
Create the service account

1

Generate a keypair

Your service account needs a keypair to sign its API requests. Generate one using OpenSSL:
# Generate the private key
openssl genrsa -out service-account.pem 2048

# Extract the public key
openssl pkey -in service-account.pem -pubout -out service-account.public.pem
Keep the private key (service-account.pem) secure - you’ll need it to sign requests.
2

Create the service account in the dashboard

  1. Navigate to Settings > Developers > Service Accounts (direct link: https://app.dfns.io/settings/service-accounts)
  2. Click New Service Account
  3. Enter a name (e.g., “Backend Server” or “Trading Bot”)
  4. Paste the contents of your public key file (including the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- lines)
  5. Click Create and sign with your passkey
3

Save the authentication token

After creation, you’ll see the service account token. Copy it immediately - it won’t be shown again.
If you lose the token, you’ll need to create a new service account.
Store both the token and private key securely. Dfns recommends using a secrets manager like AWS Secrets Manager, HashiCorp Vault, or your cloud provider’s equivalent.
4

Review permissions

By default, a service account inherits all permissions from the user who creates it. If your user has full admin access, the service account will too.To follow the principle of least privilege, create a dedicated role with only the permissions your service account needs, and assign it:
  1. Navigate to Settings > Roles and create a new role with only the required permissions
  2. Go back to Settings > Developers > Service Accounts and click on your service account
  3. Replace the inherited permissions by assigning the dedicated role
Common permission sets:
Use casePermissions needed
Create and manage walletsWallets:Create, Wallets:Read
Transfer assetsWallets:Read, Wallets:Sign
Register end usersAuth:Users:Create, Auth:Users:Read
Full wallet managementWallets:Create, Wallets:Read, Wallets:Sign, Wallets:Update
See the full list of permissions for all available options.
You can also limit the service account to a single permission at creation time by passing a permissionId in the Create Service Account API request body. The specified permission must be one that the creating user already has.

​
Service account limitations

Service accounts can perform most operations, but some actions require human interaction:
OperationService AccountNotes
Create walletsYes
Transfer assetsYesSubject to policies
Sign transactionsYesSubject to policies
Create end usersYesFor delegated wallets
Approve policy requestsNoRequires human passkey
Create other service accountsNoRequires human passkey
Modify policiesYesBut approval may require humans
When a policy triggers RequestApproval, a human user must approve the request using their passkey. Service accounts cannot approve policy requests.

​
Using your service account

You now have everything needed to make API calls:
CredentialPurpose
TokenUsed in the Authorization: Bearer <token> header
Private keyUsed to sign user action challenges for POST/PUT/DELETE requests
See the TypeScript SDK service account example for a complete implementation.

Signing requests

How to sign API requests with your service account

Permissions reference

Full list of available permissions