Reference

Token Claims

The claims in the tokens Keycard issues, and how to choose and customize them.

Keycard issues signed JSON Web Tokens (JWTs) for its access tokens, ID tokens, and refresh tokens containing the following claims.

Claims

Claim	Description
`iss`	The Keycard Zone issuer of the token.
`sub`	The subject of the token, the identity it represents: the User identifier for user tokens, or the Application identifier for application tokens. Use `sub_profile` to tell them apart.
`sub_profile`	Classifies the subject: `user` when a person authorized access, `app` when an Application acts on its own behalf.
`keycard_app_id`	The Application the token was issued for. Its value is the Application identifier.
`client_id`	The Application credential used as an OAuth client to obtain the token. Its value is the credential identifier.
`aud`	The Resource the token is intended for. Its value is the Resource identifier. Per RFC 9068, a resource server must reject a token whose `aud` is not an identifier it expects for itself.
`scope`	The permissions granted to the caller, as defined by access policy.
`sid`	The session identifier, shared across an authentication session.
`exp`	The time at which the token expires.
`iat`	The time at which the token was issued.
`jti`	A unique identifier for the token, used for audit correlation.

Customizing claims

sub, keycard_app_id, and aud are the three claims that can be configured.

User tokens: sub is the user identifier. Set it on the user, or have it auto-populated on first login via the provider’s user identifier claim.
Application tokens: sub and keycard_app_id are the Application identifier.
aud is the Resource identifier of the target Resource.

Examples

A user token, issued when a user authorizes a client. sub is the user identifier and sub_profile is user:

{
  "iss": "https://<zone-id>.keycard.cloud",
  "sub": "y93oo77cug7p7oaekhda90mcy2",
  "sub_profile": "user",
  "keycard_app_id": "orders-service",
  "client_id": "oxf9xokpfuzojrpc1lyw0uu440",
  "aud": "http://localhost:9090",
  "scope": "orders:read",
  "sid": "nr3hb6dx0a228kscyasis6uuwp",
  "exp": 1774137902,
  "iat": 1774137302,
  "jti": "019d12d2-ddec-7b0c-b293-52af0ca5a2f0"
}

An application token, issued when an Application acts on its own behalf. sub_profile is app, and sub equals keycard_app_id:

{
  "iss": "https://<zone-id>.keycard.cloud",
  "sub": "orders-service",
  "sub_profile": "app",
  "keycard_app_id": "orders-service",
  "client_id": "oxf9xokpfuzojrpc1lyw0uu440",
  "aud": "http://localhost:9090",
  "scope": "orders:read",
  "sid": "nr3hb6dx0a228kscyasis6uuwp",
  "exp": 1774137902,
  "iat": 1774137302,
  "jti": "019d12d2-ddec-7b0c-b293-52af0ca5a2f0"
}

Verifying tokens

Each Zone publishes an OpenID Connect discovery document at <issuer>/.well-known/openid-configuration and OAuth Authorization Server metadata at <issuer>/.well-known/oauth-authorization-server. Both advertise the signing keys at <issuer>/openidconnect/jwks. Verify a token’s signature against these keys and check the iss and aud claims before trusting any other claim. The Keycard SDKs ensure tokens are verified and used securely.