Skip to main content
Credentials have a lifecycle. Keys get old, team members leave, secrets end up in places they shouldn’t. This guide covers how to replace each type of credential in your Dfns integration. The general pattern is the same for all credential types: create the new one, update your systems to use it, then remove the old one.

​
Service account keypair

Service accounts authenticate with a public/private keypair. To replace it:
1

Generate a new keypair

openssl genrsa -out new-service-account.pem 2048
openssl pkey -in new-service-account.pem -pubout -out new-service-account.public.pem
2

Add the new credential

Register the new public key as a credential on your service account using Create Credential. This requires signing with the current (old) credential.
3

Update your systems

Deploy the new private key to your servers. Verify that API calls work with the new credential before proceeding.
4

Deactivate the old credential

Call Deactivate Credential on the old credential. If something goes wrong, you can reactivate it with Activate Credential.
The service account token (used in the Authorization header) stays the same. Only the signing key changes.

​
Personal Access Token keypair

PATs authenticate with a public/private keypair, just like service accounts. To replace it:
1

Generate a new keypair

openssl genrsa -out new-pat.pem 2048
openssl pkey -in new-pat.pem -pubout -out new-pat.public.pem
2

Add the new credential

Register the new public key as a credential on the PAT’s linked user using Create Credential. This requires signing with the current (old) credential.
3

Update your systems

Deploy the new private key and credential ID to your servers. Verify that API calls work with the new credential before proceeding.
4

Deactivate the old credential

Call Deactivate Credential on the old credential. If something goes wrong, you can reactivate it with Activate Credential.
The PAT access token (used in the Authorization header) stays the same. Only the signing key changes.

​
Webhook secret

Webhook secrets are set at creation time and cannot be changed. To get a new secret, replace the webhook:
1

Create a new webhook

Call Create Webhook with the same URL and event subscriptions as your existing webhook. Save the new secret.
2

Update your server

Configure your webhook handler to accept signatures from both the old and new secrets. This avoids dropping events during the transition.
3

Delete the old webhook

Once your server is using the new secret, call Delete Webhook on the old one.
4

Remove the old secret

Update your server to only accept the new secret.

​
User credentials (passkeys)

End users can register additional passkeys on new devices, then remove old ones. The flow uses Create Credential (signed with an existing passkey) or the Create Credential With Code flow for cross-domain scenarios. If you’re moving your frontend to a new domain entirely, see Registering passkeys on a new domain for a step-by-step walkthrough. See Credentials for the full credential lifecycle.

Creating a service account

Initial service account setup

Creating a personal access token

PAT setup and usage

Webhooks

Webhook setup and signature verification

Credentials reference

Credential types and creation flows

Generate a key pair

Keypair generation for all platforms
Last modified on April 14, 2026