> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.

> Describe JSON web token (JWT) claims and how they are used in Auth0.

# JSON Web Token Claims

[JSON web tokens (JWTs)](/docs/secure/tokens/json-web-tokens) claims are pieces of information asserted about a subject. For example, an [ID token](/docs/secure/tokens/id-tokens) (which is always a <Tooltip tip="JSON Web Token (JWT): Standard ID Token format (and often Access Token format) used to represent claims securely between two parties." cta="View Glossary" href="/docs/glossary?term=JWT">JWT</Tooltip>) can contain a claim called `name` that asserts that the name of the user authenticating is "John Doe". In a JWT, a claim appears as a name/value pair where the name is always a string and the value can be any JSON value. Generally, when we talk about a claim in the context of a JWT, we are referring to the name (or key). For example, the following JSON object contains three claims (`sub`, `name`, `admin`):

```json lines theme={null}
{
      "sub": "1234567890",
      "name": "John Doe",
      "admin": true
    }
```

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  To learn about OpenID Connect (OIDC) standard claims, see [OpenID Connect Scopes](/docs/get-started/apis/scopes/openid-connect-scopes) and [OpenID Connect Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims).
</Callout>

There are two types of JWT claims:

* **Registered**: standard claims registered with the [Internet Assigned Numbers Authority (IANA)](https://www.iana.org/assignments/jwt/jwt.xhtml) and defined by the [JWT specification](https://tools.ietf.org/html/rfc7519) to ensure interoperability with third-party, or external, applications. OIDC standard claims are reserved claims.
* **Custom**:  consists of non-registered public or private claims. Public claims are collision-resistant while private claims are subject to possible collisions.

## Registered claims

The JWT specification defines seven reserved claims that are not required, but are recommended to allow interoperability with [third-party applications](/docs/get-started/applications/third-party-applications/configure-third-party-applications). These are:

* `iss` (issuer): Issuer of the JWT
* `sub` (subject): Subject of the JWT (the user)
* `aud` (<Tooltip tip="Audience: Unique identifier of the audience for an issued token. Named aud in a token, its value contains the ID of either an application (Client ID) for an ID Token or an API (API Identifier) for an Access Token." cta="View Glossary" href="/docs/glossary?term=audience">audience</Tooltip>): Recipient for which the JWT is intended
* `exp` (expiration time): Time after which the JWT expires
* `nbf` (not before time): Time before which the JWT must not be accepted for processing
* `iat` (issued at time): Time at which the JWT was issued; can be used to determine age of the JWT
* `jti` (JWT ID): Unique identifier; can be used to prevent the JWT from being replayed (allows a token to be used only once)

You can see a full list of registered claims at the [IANA JSON Web Token Claims Registry](https://www.iana.org/assignments/jwt/jwt.xhtml#claims).

## Custom claims

You can define your own custom claims which you control and you can add them to a token using Actions. Here are some examples:

* Add a user's email address to an <Tooltip tip="Access Token: Authorization credential, in the form of an opaque string or JWT, used to access an API." cta="View Glossary" href="/docs/glossary?term=access+token">access token</Tooltip> and use that to uniquely identify the user.
* Add custom information stored in an Auth0 user profile to an <Tooltip tip="ID Token: Credential meant for the client itself, rather than for accessing a resource." cta="View Glossary" href="/docs/glossary?term=ID+token">ID token</Tooltip>.

As long as the Action is in place, the custom claims it adds will appear in new tokens issued when using a [refresh token](/docs/secure/tokens/refresh-tokens).

For an example showing how to add custom claims to a token, see [Sample Use Cases: Scopes and Claims](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims).

### Public claims

You can create custom claims for public consumption, which might contain generic information like name and email. If you create public claims, you must either register them or use collision-resistant names through namespacing and take reasonable precautions to make sure you are in control of the namespace you use.

In the [IANA JSON Web Token Claims Registry](https://www.iana.org/assignments/jwt/jwt.xhtml#claims), you can see some examples of public claims registered by <Tooltip tip="OpenID: Open standard for authentication that allows applications to verify users' identities without collecting and storing login information." cta="View Glossary" href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC):

* `auth_time`
* `acr`
* `nonce`

### Private claims

You can create private custom claims to share information specific to your application. For example, while a public claim might contain generic information like name and email, private claims would be more specific, such as employee ID and department name.

## Auth0 restrictions

Auth0 enforces the general restrictions on custom claims:

* custom claims payload is set to a maximum of 100KB
* a subset of OIDC and other registered standard claims or claims used internally by Auth0 cannot be customized or modified
* access tokens with an Auth0 API audience, excluding the `/userinfo` endpoint, cannot have private, non-namespaced custom claims
* only specified OIDC user profile claims can be added to access tokens

To learn more about custom claims, read [Create Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims).

## Learn more

* [Validate JSON Web Tokens](/docs/secure/tokens/json-web-tokens/validate-json-web-tokens)
* [JSON Web Token Structure](/docs/secure/tokens/json-web-tokens/json-web-token-structure)
* [JSON Web Key Sets](/docs/secure/tokens/json-web-tokens/json-web-key-sets)
* [JSON Web Key Set Properties](/docs/secure/tokens/json-web-tokens/json-web-key-set-properties)