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/v3/settings/developers/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

Assign permissions

Your service account needs permissions to perform actions. Without permissions, API calls will return “403 Forbidden”.
  1. Stay on the Service Accounts page, or navigate back to Settings > Developers > Service Accounts
  2. Click on your service account
  3. Click Add Permission
  4. Select the permissions your service account needs
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.
Follow the principle of least privilege - only grant the permissions your service account actually needs.

​
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