> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dfns.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Rotate credentials

> Replace service account keys, webhook secrets, and user credentials without downtime using Dfns credential rotation patterns and best practices.

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:

<Steps>
  <Step title="Generate a new keypair">
    ```bash theme={null}
    openssl genrsa -out new-service-account.pem 2048
    openssl pkey -in new-service-account.pem -pubout -out new-service-account.public.pem
    ```
  </Step>

  <Step title="Add the new credential">
    Register the new public key as a credential on your service account using [Create Credential](/api-reference/auth/create-credential). This requires signing with the current (old) credential.
  </Step>

  <Step title="Update your systems">
    Deploy the new private key to your servers. Verify that API calls work with the new credential before proceeding.
  </Step>

  <Step title="Deactivate the old credential">
    Call [Deactivate Credential](/api-reference/auth/deactivate-credential) on the old credential. If something goes wrong, you can reactivate it with [Activate Credential](/api-reference/auth/activate-credential).
  </Step>
</Steps>

<Note>
  The service account token (used in the `Authorization` header) stays the same. Only the signing key changes.
</Note>

## Personal Access Token keypair

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

<Steps>
  <Step title="Generate a new keypair">
    ```bash theme={null}
    openssl genrsa -out new-pat.pem 2048
    openssl pkey -in new-pat.pem -pubout -out new-pat.public.pem
    ```
  </Step>

  <Step title="Add the new credential">
    Register the new public key as a credential on the PAT's linked user using [Create Credential](/api-reference/auth/create-credential). This requires signing with the current (old) credential.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Deactivate the old credential">
    Call [Deactivate Credential](/api-reference/auth/deactivate-credential) on the old credential. If something goes wrong, you can reactivate it with [Activate Credential](/api-reference/auth/activate-credential).
  </Step>
</Steps>

<Note>
  The PAT access token (used in the `Authorization` header) stays the same. Only the signing key changes.
</Note>

## Webhook secret

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

<Steps>
  <Step title="Create a new webhook">
    Call [Create Webhook](/api-reference/webhooks/create-webhook) with the same URL and event subscriptions as your existing webhook. Save the new secret.
  </Step>

  <Step title="Update your server">
    Configure your webhook handler to accept signatures from both the old and new secrets. This avoids dropping events during the transition.
  </Step>

  <Step title="Delete the old webhook">
    Once your server is using the new secret, call [Delete Webhook](/api-reference/webhooks/delete-webhook) on the old one.
  </Step>

  <Step title="Remove the old secret">
    Update your server to only accept the new secret.
  </Step>
</Steps>

## User credentials (passkeys)

End users can register additional passkeys on new devices, then remove old ones. The flow uses [Create Credential](/api-reference/auth/create-credential) (signed with an existing passkey) or the [Create Credential With Code](/api-reference/auth/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](/guides/developers/passkey-domain-migration) for a step-by-step walkthrough.

See [Credentials](/api-reference/auth/credentials) for the full credential lifecycle.

## Related

<CardGroup cols={2}>
  <Card title="Create a service account" icon="server" href="/guides/developers/service-account">
    Initial service account setup
  </Card>

  <Card title="Create a Personal Access Token" icon="key" href="/guides/developers/personal-access-token">
    PAT setup and usage
  </Card>

  <Card title="Set up webhooks" icon="webhook" href="/guides/developers/webhooks">
    Webhook setup and signature verification
  </Card>

  <Card title="Credentials reference" icon="key" href="/api-reference/auth/credentials">
    Credential types and creation flows
  </Card>

  <Card title="Generate a key pair" icon="lock" href="/guides/developers/generate-a-key-pair">
    Keypair generation for all platforms
  </Card>
</CardGroup>