Skip to main content

JWT and JWKS

identity-service issues JWT access tokens, refresh tokens, and personal access tokens (PATs). In production they are signed with RS256, and other services verify them with the public keys at /.well-known/jwks.json, without sharing SECRET_KEY.

Tokens​

TokenDefault lifetimeVariable
Access token5 minutesJWT_ACCESS_TOKEN_LIFETIME
Refresh token7 days, rotated on every refreshJWT_REFRESH_TOKEN_LIFETIME
Personal access token30 daysPERSONAL_ACCESS_TOKEN_LIFETIME

Claims​

Besides the standard claims (iss, aud, exp, iat, jti, and user_id), access tokens carry:

ClaimContent
emailThe user's email
company_idThe company the token is for. A token is valid for one company only
user_metadataname, full_name, avatar_url, is_staff, is_company_owner, shelluiPreferences, and groups
app_metadataprovider: how the user signed in (google, magic_link, personal_access_token, …)
auth_timeWhen the user last signed in. A refresh keeps the original value
pat_id, pat_ro, pat_agmPATs only: the token ID, read-only flag, and global metrics flag

Groups claim​

user_metadata.groups is the sorted list of the user's effective group names (display_name) in the token's company. It includes groups where the user is a direct member, plus every parent group reached through nested SCIM groups. GET /api/v1/user returns the same list.

Services that authorize on groups can read this claim directly: membership is already transitive. SCIM user resources list direct memberships only.

Agent access tokens​

MCP agent access tokens are RS256 JWTs from the same issuer. Verifiers use this JWKS. sub is agent:{uuid} and aud is the MCP resource URL. When the agent has an owner user, the token includes owner_user_id, a JSON integer equal to that user's regional id (Agent.created_by_id). Personal tokens, OAuth tokens, device-login tokens, refreshed access tokens, token-exchange tokens, and downstream tokens minted for ai-service follow that rule. An agent with no owner user omits the claim. The claim is never JSON null. The rest of the agent claim set is in MCP and agents.

The Shellui CLI device grant issues an app session, not an agent token. That session does not carry owner_user_id. See CLI device login.

JWKS endpoint​

GET /.well-known/jwks.json is public and cached for 15 minutes (Cache-Control: public, max-age=900):

curl -s https://auth.example.com/.well-known/jwks.json | jq .
{
"keys": [
{
"kty": "RSA",
"use": "sig",
"alg": "RS256",
"kid": "your_key_id",
"n": "…",
"e": "AQAB"
}
]
}

Tokens have a kid header that matches the active signing key. During a key rotation, the endpoint lists the previous key too.

Verify a token​

  1. Fetch /.well-known/jwks.json and cache it for 15 minutes.
  2. Read alg (expect RS256) and kid from the JWT header.
  3. Pick the JWK with the same kid, or try each RSA key when there is no kid.
  4. Check the signature, exp, iss, aud, and the claims your service needs, such as company_id.

With PyJWT:

import jwt
from jwt import PyJWKClient

jwks_client = PyJWKClient("https://auth.example.com/.well-known/jwks.json")

token = "your_access_token_here"
signing_key = jwks_client.get_signing_key_from_jwt(token)
payload = jwt.decode(
token,
signing_key.key,
algorithms=["RS256"],
audience="shellui",
issuer="https://auth.example.com",
)

In JavaScript, jose does the same with createRemoteJWKSet.

Configure signing​

With DEBUG=false, identity-service refuses to start without an RSA private key, an issuer, and an audience.

VariableRequiredDescription
JWT_PRIVATE_KEYProductionPEM RSA private key. Use \n for newlines in .env
JWT_ISSUERProductioniss claim, for example https://auth.example.com
JWT_AUDIENCEProductionaud claim, for example shellui
JWT_PUBLIC_KEYNoPEM public key. Derived from the private key when unset
JWT_KEY_IDNokid. Defaults to the RFC 7638 JWK thumbprint
JWT_PREVIOUS_PUBLIC_KEYNoPrevious public key during a rotation, still published in JWKS
JWT_PREVIOUS_KEY_IDNokid of the previous key. Derived when unset
JWT_ACCEPT_HS256_LEGACYNofalse once RS256 is set. true with DEBUG=false fails startup (authapi.E006)

Generate a key with uv run python manage.py generate_jwt_keys, or with Docker as shown in Run identity-service. The key is 3072-bit RSA by default (2048 bits minimum).

SECRET_KEY is still required for Django sessions and CSRF, but it does not sign JWTs once JWT_PRIVATE_KEY is set. Never share it with services that verify tokens.

Paste the key into Coolify or a secret store​

generate_jwt_keys prints a quoted .env line. In Coolify or any secret UI, paste only the PEM value, not JWT_PRIVATE_KEY="…":

-----BEGIN PRIVATE KEY-----
MIIE…
-----END PRIVATE KEY-----

The same text with literal \n instead of line breaks also works, as long as there are no surrounding quotes. With the quotes, the key fails to load with InvalidByte(0, 92).

Local development​

With DEBUG=true and no JWT_PRIVATE_KEY, tokens are signed with HS256 and SECRET_KEY, and the JWKS endpoint returns {"keys":[]}. To test RS256 locally, set JWT_PRIVATE_KEY as in production.

Rotate the signing key​

  1. Generate a new key with generate_jwt_keys.
  2. Move the current public key to JWT_PREVIOUS_PUBLIC_KEY, and its kid to JWT_PREVIOUS_KEY_ID if you set a custom one.
  3. Set the new private key as JWT_PRIVATE_KEY, and update JWT_KEY_ID if you use a custom kid.
  4. Deploy. New tokens use the new key, and JWKS lists both keys.
  5. Wait until every token signed with the old key has expired: the longest of PERSONAL_ACCESS_TOKEN_LIFETIME (30 days by default) and JWT_REFRESH_TOKEN_LIFETIME (7 days).
  6. Remove the JWT_PREVIOUS_* variables. Leave JWT_ACCEPT_HS256_LEGACY unset or false. Production refuses true.

Security notes​

  • Keep JWT_PRIVATE_KEY in a secret manager or a mounted file, and never commit it
  • JWKS publishes public keys only, which is expected
  • Verifiers should always check iss and aud
  • Do not set JWT_ACCEPT_HS256_LEGACY=true when DEBUG=false. The deploy check rejects it (authapi.E006)