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

> Learn how to create collision-resistant names for custom claims.

# Create Custom Claims

To read custom claims on access and <Tooltip tip="ID Token: Credential meant for the client itself, rather than for accessing a resource." cta="View Glossary" href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip>, you must use <Tooltip tip="ID Token: Credential meant for the client itself, rather than for accessing a resource." cta="View Glossary" href="/docs/glossary?term=JSON+Web+Tokens">JSON Web Tokens</Tooltip> (JWT) and pass an <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=audience">audience</Tooltip> (`aud`) in an OIDC login flow. To learn more, read [Access Tokens](/docs/secure/tokens/access-tokens).

When configuring custom claims on JWTs, you want to avoid collisions. To keep your custom claims from colliding with any reserved claims or claims from other resources, give them a collision-resistant name. Auth0 recommends using a namespaced format.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Auth0 allows namespaced and non-namespaced claims, but certain restrictions apply (see [General restrictions](/docs/secure/tokens/json-web-tokens/create-custom-claims#general-restrictions)). To avoid name collisions, we recommend using namespaced claims. In case of collisions, the transaction won't fail, but your custom claim won't be added to your tokens.
</Callout>

## General restrictions

Auth0 applies the following restrictions to custom claims:

* Custom claims payload is set to a maximum of 100KB
* [OPENID standard claims](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) and claims used internally by Auth0 cannot be customized or modified
* <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+tokens">Access tokens</Tooltip> 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

The following claims are subject to Auth0's restrictions:

* `acr`
* `act`
* `active`
* `amr`
* `at_hash`
* `ath`
* `attest`
* `aud`
* `auth_time`
* `authorization_details`
* `azp`
* `c_hash`
* `client_id`
* `cnf`
* `cty`
* `dest`
* `entitlements`
* `events`
* `exp`
* `groups`
* `gty`
* `htm`
* `htu`
* `iat`
* `internalService`
* `iss`
* `jcard`
* `jku`
* `jti`
* `jwe`
* `jwk`
* `kid`
* `may_act`
* `mky`
* `nbf`
* `nonce`
* `object_id`
* `org_id`
* `org_name`
* `orig`
* `origid`
* `permissions`
* `roles`
* `rph`
* `s_hash`
* `sid`
* `sip_callid`
* `sip_cseq_num`
* `sip_date`
* `sip_from_tag`
* `sip_via_branch`
* `sub`
* `sub_jwk`
* `toe`
* `txn`
* `typ`
* `uuid`
* `vot`
* `vtm`
* `x5t#S256`

### Non-restricted claims

You can create claims for sensitive user information to enhance the user profile and add to the user experience. These claims are consumed by your application from ID tokens. To learn more about using non-restricted claims, read [ID Tokens](/docs/secure/tokens/id-tokens), and keep in mind [Token Best Practices](/docs/secure/tokens/token-best-practices) if you use them.

The following claims are only subject to general restrictions:

* `address`
* `birthdate`
* `email`
* `email_verified`
* `family_name`
* `gender`
* `given_name`
* `locale`
* `middle_name`
* `name`
* `nickname`
* `phone_number`
* `phone_number_verified`
* `picture`
* `preferred_username`
* `profile`
* `updated_at`
* `website`
* `zoneinfo`

## Namespaced guidelines

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  The Auth0 URN `urn:auth0` cannot be used as a namespace identifier.
</Callout>

Use the following guidelines for namespace identifiers:

* Use any non-Auth0 HTTP or HTTPS URL as a namespace identifier. Auth0 domains cannot be used as namespace identifiers, and include:

  * auth0.com
  * webtask.io
  * webtask.run
* Use a URL that you control as a namespace identifier; this allows you to avoid the risk that someone else is using the same namespace. The namespace URL does not have to point to an actual resource. It is only used as an identifier; it will not be called.
* Begin the URL with `http://` or `https://`.
* Alternatively, you can also use URN-based namespace identifiers if you use a custom API. In that case, the Auth0 URN `urn:auth0` is reserved and cannot be used as a namespace identifier.
* Create multiple namespaces, as needed.

Once you have chosen your namespace, append the claim to it to create a namespaced claim, which can be added to a token. For example:

`http://www.example.com/favorite_color`

## Non-namespaced guidelines

Use the following guidelines for non-namespaced custom claims:

* Unless absolutely necessary for your application, use public, namespaced custom claims that are collision resistant.
* Create claims with meaningful and collision resistant names. For example, use `employee_id` instead of `e_id`.
* Keep the claim names and values as light as possible, passing only the data strictly necessary for your application.
* Avoid assigning heavy payloads to custom claims.

For more examples of custom claims added to a token, see [Sample Use Cases: Scopes and Claims](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims).

## Create custom claims

Use Auth0 Actions to create custom claims. The `api` object allows you to use the method `setCustomClaim` on access tokens or ID tokens.

### Example

```js lines theme={null}
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.accessToken.setCustomClaim('myClaim', 'this is a private, non namespaced claim');
};
```

## Learn more

* [JSON Web Token Claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims)
* [OpenID Connect Scopes](/docs/get-started/apis/scopes/openid-connect-scopes)