Work with Tokens and Organizations

Learn how tokens work with Auth0’s Organizations feature and how to authenticate users belonging to an organization.

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, you pass an organization parameter in a call to the /authorize endpoint. The following examples show tokens returned when a user logs in through Organizations.

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, review Use Organization Names in Authentication API.

Third-party applications do not receive ID tokens. Access tokens still include the org_id claim shown below. To learn more, read Security Controls for Third-Party Applications.

ID token

In the following example, note that https://marketplace/roles and https://namespace.exampleco.com/ are custom claims 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": "[e-mail]",
  "picture": "https://s.gravatar.com/avatar/638",
  "updated_at": "2021-03-23T11:34:14.566z",
  "email": "[e-mail]",
  "email_verified": true,
  "sub": "auth0|602c0dcab993d10073daf680",
  "org_id": "org_9ybsU1dN2dKfDkBi"
}

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"  
  ]
}

Organization role permissions

When a user authenticates through an Organization and holds Organization roles, the access token includes permissions from those Organization roles in the permissions claim. The permissions reflect only the roles held within the active Organization for that session.

If no Organization context is present in the authentication request, tenant roles remain active and token behavior is unchanged.

The following example shows an access token for a user who holds an Organization role with read:reports and write:reports permissions within the active Organization:

{
  "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": [
    "read:reports",
    "write:reports"
  ]
}

To learn more about Organization roles, read Organization Roles.

Machine-to-Machine access to an Organization

In machine-to-machine use cases, you add an organization parameter 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.

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"
}

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, you should perform additional validation when tokens are received.

If you have configured your tenant to allow the use of organization names in the Authentication API, ID and access tokens contain both the org_id and org_name claims. If present, validate the org_name claim in addition to org_id to ensure the received values correspond to a trusted entity.

In general, using organization IDs is the preferred method for validating tokens. However, organization names can be used if they are more appropriate for your use case. To understand the potential implications of using organization names to validate tokens, review Use Organization Names in Authentication API.

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:

• Check the iss (issuer) claim to ensure the token was issued by Auth0.
• Check the org_id claim to ensure it is a value already known to the application. Validate it against a known list of Organization IDs, or check it in conjunction with the current request URL. For example, the subdomain may hint at which Organization to use 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, you should make additional checks to ensure that the Organization within your Auth0 tenant is expected.

Your API servers must also 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

• Understand How Auth0 Organizations Work
• Create Your First Organization
• Custom Development with Organizations
• Configure Organizations