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 and silently ignored in Actions and Rules.

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.

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.

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

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

Learn more