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/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 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.

   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:

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	Opt-in	Requires serviceAccountsCanApprove on the approval group and staff activation
Create policies	Yes
Create other service accounts	No	Requires human passkey
Modify policies	Yes	But approval may require humans

Service accounts can participate in policy approvals when explicitly enabled on the approval group. This feature requires activation by Dfns staff on your organization.

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