Create Namespaced Custom Claims

To keep your custom claims from colliding with any reserved claims or claims from other resources, 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, however 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. Here is an example namespace:

http://www.myexample.com/

Because a URI must be unique and this URI is under your control, you can usually avoid the risk that someone else is using the same namespace. You can also choose to store the definition of your namespace at the URI, making your namespace self-documenting. Use the following guidelines:

Use any non-Auth0 HTTP or HTTPS URL as a namespace identifier. Auth0 domains, which cannot be used as namespace identifiers include:
- auth0.com
- webtask.io
- webtask.run
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 used as an identifier; it will not be called.
You can use any number of namespaces.

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.myexample.com/favorite_color

For more examples of custom claims added to a token, see Sample Use Cases: Scopes and Claims.

Docs