> ## Documentation Index
> Fetch the complete documentation index at: https://docs-staging.auth0-mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Work with Tokens and Organizations

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

export const ReleaseStageNotice = ({feature, stage, plans, contact, terms}) => {
  const stageTextMap = {
    "beta": "Beta",
    "ea": "Early Access"
  };
  const stageText = stageTextMap[stage] || "a product release stage";
  const prsLink = "/docs/troubleshoot/product-lifecycle/product-release-stages";
  const linkify = (text, url) => {
    return <a href={url} target="_blank" rel="noreferrer" class="link">{text}</a>;
  };
  const includeDetails = (plans, contact, terms) => {
    const hasDetails = terms || plans || contact;
    if (!hasDetails) return null;
    return <span data-as="p">
            {plans && <>This feature is available for {linkify(`${plans} plans`, "https://auth0.com/pricing")}. </>}
            {contact && "To participate, contact " + contact + ". "}
            {terms && <>By using this feature, you agree to the applicable Free Trial terms in Okta's {linkify("Master Subscription Agreement", "https://www.okta.com/legal")}.</>}
        </span>;
  };
  return <Warning>
            <span data-as="p">
                <strong>The {feature} feature is in {linkify(stageText, prsLink)}.</strong>
            </span>

            {includeDetails(plans, contact, terms)}
        </Warning>;
};

<Card title="Availability varies by Auth0 plan">
  Your Auth0 plan or custom agreement affects whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

Most identity (ID) tokens and <Tooltip tip="Access Token: Authorization credential, in the form of an opaque string or JWT, used to access an API." cta="View Glossary" href="/docs/glossary?term=access+tokens">access tokens</Tooltip> returned by Auth0 are <Tooltip tip="Access Token: Authorization credential, in the form of an opaque string or JWT, used to access an API." cta="View Glossary" href="/docs/glossary?term=JSON+Web+Tokens">JSON Web Tokens</Tooltip> (JWTs) containing a variety of claims, which are pieces of information asserted about a subject. For example, an [ID token](/docs/secure/tokens/id-tokens) (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](https://tools.ietf.org/html/rfc7519) to ensure interoperability with third-party, or external, applications. [OpenID Connect (OIDC)](/docs/authenticate/protocols/openid-connect-protocol) 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](/docs/secure/tokens/json-web-tokens/create-custom-claims), 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](/docs/secure/tokens/json-web-tokens/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.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  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](/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api).
</Callout>

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  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](/docs/get-started/applications/third-party-applications/security-controls).
</Callout>

### 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.

```json lines theme={null}
{
  "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"
}
```

### Access token

```json lines theme={null}
{
  "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

<ReleaseStageNotice feature="Organization Roles" stage="ea" terms="true" contact="Auth0 Support" />

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:

```json lines theme={null}
{
  "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](/docs/manage-users/organizations/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.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  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](/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api).
</Callout>

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

```json lines theme={null}
{
  "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.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  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](/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api).
</Callout>

**For web applications:**

If no `organization` parameter was passed to the `/authorize` endpoint, but an `org_id` claim is present in the <Tooltip tip="ID Token: Credential meant for the client itself, rather than for accessing a resource." cta="View Glossary" href="/docs/glossary?term=ID+token">ID token</Tooltip>, 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](/docs/manage-users/organizations/organizations-overview)
* [Create Your First Organization](/docs/manage-users/organizations/create-first-organization)
* [Custom Development with Organizations](/docs/manage-users/organizations/custom-development)
* [Configure Organizations](/docs/manage-users/organizations/configure-organizations)