---
title: Token Claims | Keycard
description: 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`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1)            | The Keycard Zone issuer of the token.                                                                                                                                                                                                                                                            |
| [`sub`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2)            | The subject of the token, the identity it represents: the [User identifier](/concepts/users/#identifier/index.md) for user tokens, or the [Application identifier](/concepts/applications/#identifier/index.md) 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](/concepts/applications/#identifier/index.md).                                                                                                                                                                |
| [`client_id`](https://datatracker.ietf.org/doc/html/rfc8693#section-4.3)        | The Application credential used as an OAuth client to obtain the token. Its value is the credential identifier.                                                                                                                                                                                  |
| [`aud`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3)            | The Resource the token is intended for. Its value is the [Resource identifier](/concepts/resources/#identifier/index.md). Per [RFC 9068](https://datatracker.ietf.org/doc/html/rfc9068#section-4), a resource server must reject a token whose `aud` is not an identifier it expects for itself. |
| [`scope`](https://datatracker.ietf.org/doc/html/rfc8693#section-4.2)            | The permissions granted to the caller, as defined by [access policy](/admin/access-policies/index.md).                                                                                                                                                                                           |
| [`sid`](https://openid.net/specs/openid-connect-frontchannel-1_0.html#OPLogout) | The session identifier, shared across an authentication session.                                                                                                                                                                                                                                 |
| [`exp`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4)            | The time at which the token expires.                                                                                                                                                                                                                                                             |
| [`iat`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6)            | The time at which the token was issued.                                                                                                                                                                                                                                                          |
| [`jti`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.7)            | 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](/concepts/users/#identifier/index.md). Set it on the user, or have it auto-populated on first login via the provider’s [user identifier claim](/concepts/providers/#user-identifier-claim/index.md).
- Application tokens: `sub` and `keycard_app_id` are the [Application identifier](/concepts/applications/index.md).
- `aud` is the [Resource identifier](/concepts/resources/#identifier/index.md) 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.