# Signing Key Rotation

Learn how to rotate the keys FusionAuth uses to sign JWTs, SAML responses, and webhook events.

> For the index of this section of the site, see [llms.txt](https://fusionauth.io/docs/llms.txt)

FusionAuth signs JWTs with keys stored in [Key Master](https://fusionauth.io/docs/security/tokens-and-keys/key-master.md). Your applications verify the signature to confirm that FusionAuth issued the token. FusionAuth also signs SAML responses and webhook events with Key Master keys. To rotate a signing key, create a new key, switch your configuration to the new key, and keep the old key for verification until the tokens the old key signed expire.

For API keys, see [API Key Rotation](https://fusionauth.io/docs/security/tokens-and-keys/api-key-rotation.md). For more information about JWT signing, see [Tokens](https://fusionauth.io/articles/tokens.md).

## Find Keys Due for Rotation

Since `1.45.0`, the [Key Search API](https://fusionauth.io/docs/apis/keys/search-for-keys.md) accepts a wildcard search ordered by expiration. A script can then find every key that expires within a set period.

The following script uses `jq` and `bash` to list the keys that expire in the next 30 days. The script is in the [FusionAuth example scripts GitHub repository](https://github.com/FusionAuth/fusionauth-example-scripts).

Script to query for keys expiring in 30 days

```shell
#!/bin/bash

API_KEY=...
FA_HOSTNAME=http://localhost:9011

# default to 30 days out. any keys expiring before this will be printed
DAYS_TILL_EXPIRATION=30

# finds current unix timestamp (the %s format works the same on GNU and BSD/macOS date)
curdate=`date +%s`

curdateinmillis=$(($curdate * 1000))
expdatemillis=$(($DAYS_TILL_EXPIRATION * 24 * 60 * 60 * 1000))
targetdateinmillis=$(($curdateinmillis + $expdatemillis))

start=0
increment=25

total=`curl -s -H "Authorization: $API_KEY" $FA_HOSTNAME'/api/key/search?orderBy=expiration%20ASC' | jq '.total'`

keysdata=""

# loop over requests to FusionAuth key search API
while [[ $start -lt $total ]]; do
  res=`curl -s -H "Authorization: $API_KEY" $FA_HOSTNAME'/api/key/search?orderBy=expiration%20ASC&startRow='$start'&numberOfResults='$increment | jq -r '.keys[]| select(.expirationInstant != null) |[.expirationInstant,.id]|@csv'`

  # for each set of results, loop over them and grab the expiration instant
  for row in $res; do
    exp=`echo $row|awk -F, '{print $1}'`
    if [[ $exp -gt $targetdateinmillis ]]; then
      # seen key far enough in the future, bail
      exit 0
    fi
    echo $row
  done

  # if we get here, there are more rows to pull and keys are still before our DAYS_TILL_EXPIRATION value
  start=$(($start + $increment))
done

exit
```

Run the script on a schedule, such as a `cron` job, then rotate the returned keys.

Before `1.45.0`, the Key Search API doesn't exist. Retrieve every key with the [Retrieve a Key API](https://fusionauth.io/docs/apis/keys/retrieve-a-key.md), then filter the response on **`expirationInstant`**. HMAC keys have no expiration, so track the age of an HMAC key with **`insertInstant`**.

## Rotate a Signing Key

Suppose FusionAuth signs JWTs with key `JS1`. To rotate key `JS1`:

1.  Create key `JS2` in Key Master. Use the same algorithm and key length as key `JS1`.
2.  Switch every Tenant and Application that signs with key `JS1` to key `JS2`. At the same time, add key `JS1` to **Access token verification keys**, **Id token verification keys**, or both. Make the change at the Tenant level, or at the Application level when the Application overrides the JWT settings. FusionAuth `1.69.0` and later support verification keys.
3.  Wait until every token signed by key `JS1` expires. The wait depends on the JWT lifetime. For example, with a five-minute JWT lifetime, wait ten minutes to allow for clock skew.
4.  Delete key `JS1`.

The steps assume that only FusionAuth uses keys `JS1` and `JS2`. When another system holds the private key, such as an externally managed RSA key, import key `JS2` instead of creating key `JS2`. Then update the other system to use key `JS2` before you delete key `JS1`.

## Find Every Use of a Key

To switch every configuration to the new key, retrieve each object and look for the Id of the old key. Check the following fields:

*   JWT configuration
    *   `tenant.jwtConfiguration.accessTokenKeyId`
    *   `tenant.jwtConfiguration.accessTokenVerificationKeyIds`
    *   `tenant.jwtConfiguration.idTokenKeyId`
    *   `tenant.jwtConfiguration.idTokenVerificationKeyIds`
    *   `application.jwtConfiguration.accessTokenKeyId`
    *   `application.jwtConfiguration.accessTokenVerificationKeyIds`
    *   `application.jwtConfiguration.idTokenKeyId`
    *   `application.jwtConfiguration.idTokenVerificationKeyIds`
*   [Entity Type](https://fusionauth.io/docs/concepts/types/entity-management.md#entity-types) JWT configuration
    *   `entityType.jwtConfiguration.accessTokenKeyId`
*   External JWT IdP
    *   `identityProvider.defaultKeyId`
    *   `identityProvider.verificationKeyIds`
*   Application SAML v2
    *   `application.samlv2Configuration.assertionEncryptionConfiguration.keyTransportEncryptionKeyId`
    *   `application.samlv2Configuration.defaultVerificationKeyId`
    *   `application.samlv2Configuration.keyId`
    *   `application.samlv2Configuration.logout.defaultVerificationKeyId`
    *   `application.samlv2Configuration.logout.singleLogout.keyId`
    *   `application.samlv2Configuration.logout.keyId`
    *   `application.samlv2Configuration.logout.verificationKeyIds`
    *   `application.samlv2Configuration.verificationKeyIds`
*   SAML v2 IdP
    *   `identityProvider.keyId`
    *   `identityProvider.requestSigningKeyId`
    *   `identityProvider.verificationKeyIds`
*   Webhook signature
    *   `webhook.signatureConfiguration.signingKeyId`

## Confirm the Rotation

Log in to an Application that used key `JS1`. Decode the new access token, and confirm that the `kid` header matches the **Kid** of key `JS2` in Key Master.

Related

[Security Key Rotation Learn about the keys and secrets FusionAuth uses, and how rotation differs for each one. key rotationjwt signing keysecurity](https://fusionauth.io/docs/security/tokens-and-keys/key-rotation.md)

[Security API Key Rotation Learn how to rotate FusionAuth API keys without interrupting the scripts and servers that use them. key rotationsecuritydefense in depth](https://fusionauth.io/docs/security/tokens-and-keys/api-key-rotation.md)

[Security Client Secret Rotation Learn how to rotate the client secret of a FusionAuth Application or Entity. key rotationsecuritydefense in depth](https://fusionauth.io/docs/security/tokens-and-keys/client-secret-rotation.md)

[Migrate Password-Hashing Algorithms This is a reference for all of the current password hashing algorithms support by FusionAuth out of the box. cryptographysecurity](https://fusionauth.io/docs/migrate/password-hashes/algorithms.md)
---

## Other pages in Tokens And Keys

> For the full index of this section, see [Security](https://fusionauth.io/docs/llms-security.txt).

- [API Key Rotation](https://fusionauth.io/docs/security/tokens-and-keys/api-key-rotation.md): Learn how to rotate FusionAuth API keys without interrupting the scripts and servers that use them.
- [Client Secret Rotation](https://fusionauth.io/docs/security/tokens-and-keys/client-secret-rotation.md): Learn how to rotate the client secret of a FusionAuth Application or Entity.
- [Key Master](https://fusionauth.io/docs/security/tokens-and-keys/key-master.md): Learn how to create, import, and manage signing keys and certificates with Key Master.
- [Key Rotation](https://fusionauth.io/docs/security/tokens-and-keys/key-rotation.md): Learn about the keys and secrets FusionAuth uses, and how rotation differs for each one.
- [Token Storage](https://fusionauth.io/docs/security/tokens-and-keys/token-storage.md): Learn how to secure tokens generated by FusionAuth.
