Custom Claims


Custom claims are claims that you define, control, and add to a token using a rule. For example, you may want to add a user's email address to an Access Token and use that to uniquely identify the user, or you may want to add custom information stored in an Auth0 user profile to an ID Token.

Remember that all claims included in a token must have unique names. To keep your custom claims from colliding with the OpenID Connect (OIDC) standard claims, you must give them an identifier that conforms to a namespaced format. For example, your custom claim could be named

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

Some guidelines:

  • The namespace URL does not have to point to an actual resource because it's only being used as an identifier; it will not be called.
  • Any non-Auth0 HTTP or HTTPS URL can be used as a namespace identifier, and any number of namespaces can be used., and are Auth0 domains and therefore cannot be used as a namespace identifier.

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

Refresh tokens and custom claims

As long as your rule is in place, the custom claims it adds will appear in new tokens issued when using a Refresh Token. Although new tokens do not automatically inherit custom claims, rules run during the Refresh Token flow, so the same code will be executed. This allows you to add or change custom claims in newly-issued tokens without forcing previously-authorized applications to obtain a new Refresh Token.

Keep reading