Creating a service account

How to create a service account and assign it permissions for server-to-server API access

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 case	Permissions needed
   Create and manage wallets	Wallets:Create, Wallets:Read
   Transfer assets	Wallets:Read, Wallets:Sign
   Register end users	Auth:Users:Create, Auth:Users:Read
   Full wallet management	Wallets: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:

Operation	Service Account	Notes
Create wallets	Yes
Transfer assets	Yes	Subject to policies
Sign transactions	Yes	Subject to policies
Create end users	Yes	For delegated wallets
Approve policy requests	No	Requires human passkey
Create other service accounts	No	Requires human passkey
Modify policies	Yes	But 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:

Credential	Purpose
Token	Used in the Authorization: Bearer <token> header
Private key	Used to sign user action challenges for POST/PUT/DELETE requests

See the TypeScript SDK service account example for a complete implementation.

Related

Signing requests

How to sign API requests with your service account

Permissions reference

Full list of available permissions