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.

​
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. See Credentials for the full credential lifecycle.

Creating a service account

Initial service account setup

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 7, 2026