Work with Tokens and Organizations

Availability varies by Auth0 plan

Your Auth0 plan or custom agreement affects whether this feature is available. To learn more, read Pricing.

Most identity (ID) tokens and access tokens returned by Auth0 are JSON Web Tokens (JWTs) containing a variety of claims, which are pieces of information asserted about a subject. For example, an ID token (which is always a JWT) can contain a claim called name that asserts that the name of the user authenticating is "John Doe".

There are two types of JWT claims:

  • Registered: Claims defined by the JWT specification to ensure interoperability with third-party, or external, applications. OpenID Connect (OIDC) standard claims are reserved claims.

  • Custom: Claims that you define yourself. These claims can be non-registered, collision-resistant public claims or non-registered, non-public private claims subject to collision. Name these claims carefully, such as through namespacing, to avoid collision with reserved claims or other custom claims. It can be challenging to deal with two claims of the same name that contain differing information.

To learn more about claims, read JSON Web Token Claims.

Authenticate users through an organization

To authenticate a user through an organization, an organization parameter is added to a call to the /authorize endpoint. Examples of tokens returned when a user logs in through organizations are provided below.

ID token

In the following example, note that https://marketplace/roles and https://namespace.exampleco.com/ are custom claims that have been added to the token, while the other included claims are standard.

{
  "https://marketplace/roles": [
    "marketplace-administrator"
  ],
  "https://namespace.exampleco.com": "my custom claim",
  "nickname": "firstName.lastName",
  "name": "firstName.lastName@email.com",
  "picture": "https://s.gravatar.com/avatar/638",
  "updated_at": "2021-03-23T11:34:14.566z",
  "email": "username@exampleco.com",
  "email_verified": true,
  "sub": "auth0|602c0dcab993d10073daf680",
  "org_id": "org_9ybsU1dN2dKfDkBi"
}

Was this helpful?

/

Access token

{
  "iss": "https://exampleco.auth0.com/",
  "sub": "auth0|602c0dcab993d10073daf680",
  "aud": [
    "https://example-api/",
    "https://exampleco.auth0.com/userinfo"  
  ],
  "iat": 1616499255,
  "exp": 1616585655,
  "azp": "ENDmmAJsbwI1hOG1KPJddQ8LHjV6kLkV",
  "scope": "openid profile email",
  "org_id": "org_9ybsU1dN2dKfDkBi",
  "permissions": [
    "delete:stuff",
    "read:stuff",
    "write:stuff"  
  ]
}

Was this helpful?

/

Machine-to-Machine access to an organization

In machine-to-machine use cases, an organization parameter is added to the Client Credentials request to the /oauth/token endpoint so that an application can obtain an access token for itself rather than a user.

Note: By default, ID and access tokens only include organization IDs. However, you can configure your tenant to allow the use of organization names in the Authentication API. When configured, ID and access tokens contain both the org_id and org_name claims. To learn more, read Use Organization Names in the Authentication API.

The following code sample is an example access token returned in machine-to-machine use cases:

{
  "iss": "https://exampleco.auth0.com/",
  "sub": "CS2MNgcX1VZFCJaEzfKw2VPAAS0gzhqP@clients",
  "aud": "https://example-api",
  "iat": 1727782196,
  "exp": 1727868596,
  "scope": "scope1 scope2",
  "org_id": "org_vIK75NKFvaozQsFy",
  "org_name": "acme",
  "gty": "client-credentials",
  "azp": "CS2MNgcX1VZFCJaEzfKw2VPAAS0gzhqP"
}

Was this helpful?

/

Validate tokens

When the organization parameter is added to a call to the /authorize endpoint or the /oauth/token endpoint, Auth0 SDKs automatically validate the org_id claim, which is returned as part of any generated tokens. However, for security purposes, additional validation should be performed when tokens are received.

For web applications:

If no organization parameter was passed to the /authorize endpoint, but an org_id claim is present in the ID token, then your application should validate the claim to ensure that the value received is expected or known and that it corresponds to an entity your application trusts, such as a paying customer. If the claim cannot be validated, then the application should deem the token invalid.

For APIs:

If an org_id claim is present in the access token, then your API should validate the claim to ensure that the value received is expected or known and that it corresponds to an entity your application trusts, such as a paying customer. If the claim cannot be validated, then the API should deem the token invalid.

In particular:

  • The iss (issuer) claim should be checked to ensure the token was issued by Auth0.

  • The org_id claim should be checked to ensure it is a value that is already known to the application. This could be validated against a known list of organization IDs, or perhaps checked in conjunction with the current request URL. For example, the subdomain may hint at which organization should be used when validating the ID Token.

Normally, validating only the issuer would be enough to ensure that the token was issued by Auth0. In the case of organizations, however, additional checks should be made to ensure that the organization within your Auth0 tenant is expected.

It is also very important that your API servers segment access to data and resources based on the org_id. This ensures that only information about a given organization can be accessed or modified when the org_id value corresponding to that organization is received in the access token.

Learn more