Create Custom Claims

To read custom claims on access and ID tokens, you must use JSON Web Tokens (JWT) and pass an audience (aud) in an OIDC login flow. To learn more, read 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.

Auth0 allows namespaced and non-namespaced claims, but certain restrictions apply (see 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.

General restrictions

Auth0 applies the following restrictions to custom claims:

Custom claims payload is set to a maximum of 100KB
OPENID standard claims and 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

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, and keep in mind 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

The Auth0 URN urn:auth0 cannot be used as a namespace identifier.

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.