Supabase uses JWT signing keys to sign authentication tokens. By default, Supabase generates a new signing key on startup, but you can also use your own signing keys. This is useful if you want to generate your own tokens or if you want to use the same signing keys across multiple Supabase instances.

Generate a signing key

First, generate a new signing key using the Supabase CLI:

npx supabase gen signing-key --algorithm ES256

This will output a new signing key in JSON format to the terminal.

Note: If you already have a supabase/signing_key.json file, the CLI will ask if you want to overwrite it. If you want to keep the existing signing key, you can choose “No” and the CLI will not output a new signing key.

Local Development

For local development, save the signing key in your supabase directory, such as supabase/signing_key.json. Supabase requires the local signing key to be contained in an array, so you need to wrap the output in square brackets. For example, if your output looks like this:

{
  "kty": "EC",
  "d": "N8sXo9n2e5Z19sXo9n2e5Z1",
  "use": "sig",
  "crv": "P-256",
  "kid": "my-key-id",
  "x": "f83OJ3D2xF4",
  "y": "x_FEzRu9c"
}

You need to wrap it like this:

[
  {
    "kty": "EC",
    "d": "N8sXo9n2e5Z19sXo9n2e5Z1",
    "use": "sig",
    "crv": "P-256",
    "kid": "my-key-id",
    "x": "f83OJ3D2xF4",
    "y": "x_FEzRu9c"
  }
]

Save this into a file called supabase/signing_key.json.

Then, edit the config.toml file and add the following lines to the [auth] section:

[auth]
signing_keys_path = "./signing_key.json"

This will tell Supabase to use your signing key instead of generating a new one on startup. After editing config.toml, you need to restart Supabase to reload the configuration:

npx supabase stop
npx supabase start

Hosted Supabase

If you are using the hosted version of Supabase, you can set the signing keys in the Supabase dashboard. Go to the “Settings” tab, then click on “JWT Signing Keys”.

If you already have a standby key, you’ll need to remove it before you can add a new one. To remove a standby key, click the three dots next to the key and select “Move to previously used”. After removing the existing standby key, you can add your new signing key as described above.

Important: This signing key must not by in an array. It should be the raw JSON object that was generated by the Supabase CLI.

Click “Create Standby Key”. In the dialog select “Import an existing key” and paste in your previously generated signing key. Click the “Create Standby Key” button to save the new signing key.

Click “Rotate Keys” to make the new signing key active. This will rotate the keys and make the new signing key the active key for signing tokens.

Important Notes

• The Supabase CLI-generated signing key contains both verify and sign keys because Supabase itself needs to do both. However, some tools like jose will fail signing if object contains a verify key. If you encounter this issue, you can remove the verify key from the signing key JSON file before using it with jose.
• If your app has users with a persisted session, changing the signing key will invalidate all existing tokens. This means that users will need to log in again to obtain new tokens signed with the new key. Make sure to communicate this change to your users if you are changing the signing key in a production environment. If you’re using the JavaScript client, you can call supabase.auth.refreshSession() to refresh the session and obtain a new token without requiring the user to log in again.
• You can tell if a user has an invalid JWT by checking the error property of the user object returned by supabase.auth.getUser(). If the JWT is invalid, the error property will contain a code property of "bad_jwt".