Create a service account

​

When to use a service account

• 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 authenticates by signing API requests with a private key. Generate the keypair yourself — only the public key is uploaded to DFNS; the private key never leaves your control and DFNS never sees it. Generate it on the machine or secrets manager that will use it, not on a shared workstation.

# Generate the private key with owner-only permissions from the start
(umask 077 && openssl genrsa -out service-account.pem 2048)

# Extract the public key — this is the only part you give to DFNS
openssl pkey -in service-account.pem -pubout -out service-account.public.pem

RSA 2048 is the minimum; DFNS also accepts ECDSA (P-256) and Ed25519 public keys (see the note in the next step) if you prefer a smaller, modern key. Generate a dedicated key for this service account — don’t reuse one across accounts or environments. See Generating and storing keys safely below before you continue.

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

DFNS accepts only PEM-encoded SPKI public keys — the -----BEGIN PUBLIC KEY----- … -----END PUBLIC KEY----- block produced by openssl pkey -pubout (for ECDSA, EdDSA, or RSA keys). OpenSSH-format keys (ssh-ed25519 AAAA..., ssh-rsa AAAA..., ecdsa-sha2-nistp256 ... — the contents of a .pub file) are rejected as the wrong format. If your key is in OpenSSH format, convert it to PEM first: ssh-keygen -f id_ed25519.pub -e -m PKCS8.

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.

Service account tokens are valid for 2 years by default, which is also the maximum. To set a shorter lifetime, pass daysValid (or secondsValid) when creating the service account via the API; the dashboard always uses the default. When a token expires, requests fail with a 401, and you need to rotate the credential.

4

Review permissions

By default, a new service account has no permissions. You must explicitly assign a role with the permissions it needs:

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. Assign 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 assign a permission at creation time by passing a permissionId in the Create Service Account API request body. The creating user must have the PermissionsAssign permission.

​

Generating and storing keys safely

• Generate it where it will run. Create the keypair on the server or secrets manager that will use it. Only the public key goes to DFNS; the private key should travel no further than it has to.
• Lock down the file. Restrict the private key to its owner (chmod 600, or the umask 077 shown above). For extra protection at rest, encrypt it with a passphrase (openssl genrsa -aes256 -out service-account.pem 2048).
• Never commit it. Keep the private key and token out of source control, container images, CI logs, and committed .env or example files. Load them from a secrets manager (AWS Secrets Manager, HashiCorp Vault, or your cloud provider’s equivalent) or from environment variables injected at runtime.
• One key per account and environment. Use separate service accounts — and separate keys — for production and non-production, and for distinct automations, so you can revoke one without disrupting the others.
• Rotate on a schedule and on suspicion. Rotate the key periodically, and immediately if it may have been exposed. See credential rotation.
• Scope permissions tightly. Give the account only the permissions its job needs (see Review permissions) so a leaked key has a limited blast radius.

​

Service account limitations

​

Using your service account

​

Related