Skip to main content
Personal Access Tokens (PATs) are long-lived authentication tokens tied to a specific user. They let you automate API calls under that user’s identity, with optional scope restrictions and expiration.
For most backend integrations, you should use a service account instead. Service accounts are independent machine identities, not tied to any user. Use a PAT only when you specifically need to act as a particular user.

​
When to use a PAT

PATs are for cases where the action must be attributed to a specific user: your server performs operations in a user’s wallet while maintaining their identity as the actor. This is the recommended approach over registering a server-controlled credential on the user’s account. You can also create reduced-permissions tokens representing the user (e.g.: read-only) for automating without reducing the user’s own permissions.

​
PAT vs service account

PATService account
IdentityTied to a userIndependent machine identity
PermissionsIntersection of user and token permissionsIndependent permissions
LifecycleStops working when user is deactivatedIndependent
ExpirationOptionalOptional
Use caseActing on behalf of a userServer-to-server automation

​
Create a PAT

1

Generate a keypair

Your PAT needs its own keypair for signing API requests. Generate one using OpenSSL:
# Generate the private key
openssl genrsa -out pat.pem 2048

# Extract the public key
openssl pkey -in pat.pem -pubout -out pat.public.pem
See Generate a key pair for other algorithms and platforms.
Generate a new keypair specifically for this PAT. Do not reuse a key from a service account or another credential. Each credential must have its own unique keypair.
2

Create the PAT in the dashboard

  1. Navigate to Settings > Developers > Personal Access Tokens (direct link: https://app.dfns.io/settings/developers/personal-access-tokens)
  2. Click New Personal Access Token
  3. Enter a name (e.g., “Wallet Monitor” or “Backend Automation”)
  4. Paste the contents of your public key file (including the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- lines)
  5. Optionally set an expiration
  6. Click Create and sign with your passkey
Creating a PAT requires the Auth:Pats:Create permission.
3

Save the token and credential ID

After creation, you receive:
  • Access token — used in the Authorization: Bearer <token> header
  • Credential ID (cr-...) — used to configure the SDK signer
Copy both values immediately. The access token is shown once and cannot be retrieved later. If you lose it, create a new PAT.
Store the access token and private key in a secrets manager (AWS Secrets Manager, HashiCorp Vault, or equivalent).
4

Assign permissions (optional)

By default, a PAT can do anything the linked user can do. You can restrict it by assigning a role with fewer permissions.The effective permissions on every request are the intersection of the user’s permissions and the token’s permissions. This means:
  • Reducing the user’s permissions immediately restricts all their PATs
  • A PAT can never exceed the user’s current permissions, even if the token’s own role is broader
See the full list of permissions.

​
Using your PAT

Configure the SDK with your PAT’s access token and the private key you generated in step 1. The setup is identical to a service account, just with the PAT credentials instead. 
import { DfnsApiClient } from '@dfns/sdk'
import { AsymmetricKeySigner } from '@dfns/sdk-keysigner'

const signer = new AsymmetricKeySigner({
  credId: 'cr-...', // Credential ID from PAT creation
  privateKey: process.env.PAT_PRIVATE_KEY!,
})

const dfns = new DfnsApiClient({
  baseUrl: 'https://api.dfns.io',
  orgId: 'or-...',
  authToken: process.env.PAT_ACCESS_TOKEN!,
  signer,
})

// Now use dfns as usual
const { items } = await dfns.wallets.listWallets()
Request signing vs wallet signing: the private key in the signer signs API requests (proving your identity to Dfns). This is separate from wallet operations like Generate Signature, which use the wallet’s MPC keys managed by Dfns. You never need your PAT’s private key for blockchain transactions.

​
Lifecycle management

PATs can be deactivated, reactivated, and deleted through the dashboard or API. If the linked user is deactivated, all their PATs stop working. The PAT records themselves are not deleted, so reactivating the user restores PAT access. To rotate the signing keypair without replacing the PAT itself, see Rotating credentials.

Generate a key pair

Supported algorithms and generation examples

Signing requests

How API request signing works

Permissions reference

Full list of available permissions

PAT API reference

API endpoints and object schema
Last modified on April 14, 2026