Signing Keys

Each environment has its own RSA signing keys used to sign JWT access tokens and OIDC ID tokens. Paylent supports key rotation so you can generate new keys without invalidating existing tokens.

How Keys Work

When you generate a signing key, Paylent creates a 4096-bit RSA key pair. The private key signs tokens, and the public key is published at /.well-known/jwks.json so clients can verify signatures locally.

Every environment has one primary key — the key used to sign new tokens. You can have multiple active keys, but only the primary key signs.

Generating a Key

Dashboard

Go to Signing Keys in the sidebar and click Generate Key. The new key automatically becomes the primary key.

Management API

curl -X POST https://acme-test.paylent.com/api/signing-keys \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{
    "data": {
      "type": "signing_key",
      "attributes": {}
    }
  }'

The response includes the key’s kid (Key ID), algorithm, and status.

Key Rotation

To rotate keys without breaking existing tokens:

1. Generate a new key — it becomes the primary and signs all new tokens
2. Keep the old key active — existing tokens remain verifiable via JWKS
3. Deactivate the old key when you’re confident all old tokens have expired

Deactivating a Key

Deactivating a key removes it from the JWKS endpoint. Any tokens signed by the deactivated key can no longer be verified via JWKS.

curl -X PATCH https://acme-test.paylent.com/api/signing-keys/KEY_ID/deactivate \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

If you deactivate the primary key, Paylent automatically promotes the most recently created active key.

Setting a Primary Key

To manually set which key signs new tokens:

In the dashboard, go to the key’s detail page and click Set as Primary.

JWKS Endpoint

The JSON Web Key Set endpoint publishes the public keys of all active signing keys:

GET https://acme-test.paylent.com/.well-known/jwks.json

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "Mq8N-x5vP2k",
      "use": "sig",
      "alg": "RS256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

OAuth clients and resource servers use this endpoint to verify JWT signatures. Each JWT includes a kid header that identifies which key signed it, so clients can find the correct public key in the JWKS.

Token Verification

JWTs signed by Paylent include:

Header	Description
alg	RS256 — RSA signature with SHA-256
kid	Key ID matching an entry in JWKS
typ	at+jwt for access tokens, JWT for ID tokens

To verify a token:

1. Fetch the JWKS from /.well-known/jwks.json
2. Find the key matching the token’s kid header
3. Verify the RS256 signature with the public key
4. Check exp (expiration) and iss (issuer) claims

Most OAuth/OIDC libraries handle this automatically when configured with the OIDC discovery URL.

Key States

State	Signs tokens	In JWKS	Can verify old tokens
Primary	Yes	Yes	Yes
Active	No	Yes	Yes
Deactivated	No	No	No (via JWKS)