Create Namespaced Custom Claims

To keep your custom claims from colliding with any reserved claims or claims from other resources, you must give them a globally unique name using a namespaced format.

By default, Auth0 always enforces namespacing; any custom claims with non-namespaced identifiers will be silently excluded from tokens.

We do allow non-OIDC claims without a namespace for legacy tenants using a non-OIDC-conformant pipeline with the Legacy User Profile enabled, but we strongly recommend that legacy tenants migrate to an OIDC-conformant flow.

Namespaces are arbitrary identifiers, so technically you can call your namespace anything you want. However, using the URI of a resource you control is conventional (following the way XML namespaces are defined).

Example namespace:

Because a URI must be unique and because this URI is under your control, you can generally avoid the risk that someone else is using the same namespace. You can also optionally store the definition of your namespace at the URI, making your namespace self-documenting.


  • Any non-Auth0 HTTP or HTTPS URL can be used as a namespace identifier. Auth0 domains, which cannot be used as namespace identifiers, include:,, and

  • Although ideally you will use a URI that you control, the namespace URI does not have to point to an actual resource. It is only being used as an identifier; it will not be called.

  • You can use any number of namespaces.

Adding a namespace to a claim

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

Example namespaced claim:

For an example showing how to add custom claims to a token, see Sample Use Cases: Scopes and Claims.

Read more