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
| Token | Default lifetime | Variable |
|---|---|---|
| Access token | 5 minutes | JWT_ACCESS_TOKEN_LIFETIME |
| Refresh token | 7 days, rotated on every refresh | JWT_REFRESH_TOKEN_LIFETIME |
| Personal access token | 30 days | PERSONAL_ACCESS_TOKEN_LIFETIME |
Claims
Besides the standard claims (iss, aud, exp, iat, jti, and user_id), access tokens carry:
| Claim | Content |
|---|---|
email | The user's email |
company_id | The company the token is for. A token is valid for one company only |
user_metadata | name, full_name, avatar_url, is_staff, is_company_owner, shelluiPreferences, and groups |
app_metadata | provider: how the user signed in (google, magic_link, personal_access_token, …) |
auth_time | When the user last signed in. A refresh keeps the original value |
pat_id, pat_ro, pat_agm | PATs 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
- Fetch
/.well-known/jwks.jsonand cache it for 15 minutes. - Read
alg(expectRS256) andkidfrom the JWT header. - Pick the JWK with the same
kid, or try each RSA key when there is nokid. - Check the signature,
exp,iss,aud, and the claims your service needs, such ascompany_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.
| Variable | Required | Description |
|---|---|---|
JWT_PRIVATE_KEY | Production | PEM RSA private key. Use \n for newlines in .env |
JWT_ISSUER | Production | iss claim, for example https://auth.example.com |
JWT_AUDIENCE | Production | aud claim, for example shellui |
JWT_PUBLIC_KEY | No | PEM public key. Derived from the private key when unset |
JWT_KEY_ID | No | kid. Defaults to the RFC 7638 JWK thumbprint |
JWT_PREVIOUS_PUBLIC_KEY | No | Previous public key during a rotation, still published in JWKS |
JWT_PREVIOUS_KEY_ID | No | kid of the previous key. Derived when unset |
JWT_ACCEPT_HS256_LEGACY | No | false 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
- Generate a new key with
generate_jwt_keys. - Move the current public key to
JWT_PREVIOUS_PUBLIC_KEY, and itskidtoJWT_PREVIOUS_KEY_IDif you set a custom one. - Set the new private key as
JWT_PRIVATE_KEY, and updateJWT_KEY_IDif you use a customkid. - Deploy. New tokens use the new key, and JWKS lists both keys.
- Wait until every token signed with the old key has expired: the longest of
PERSONAL_ACCESS_TOKEN_LIFETIME(30 days by default) andJWT_REFRESH_TOKEN_LIFETIME(7 days). - Remove the
JWT_PREVIOUS_*variables. LeaveJWT_ACCEPT_HS256_LEGACYunset orfalse. Production refusestrue.
Security notes
- Keep
JWT_PRIVATE_KEYin a secret manager or a mounted file, and never commit it - JWKS publishes public keys only, which is expected
- Verifiers should always check
issandaud - Do not set
JWT_ACCEPT_HS256_LEGACY=truewhenDEBUG=false. The deploy check rejects it (authapi.E006)
Related
- Metrics and access tokens: personal access tokens
- OAuth login: how tokens reach the shell
- Security hardening