> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-docs-event-stream-action-templates.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Learn how tokens work with Auth0's Organizations feature and how to authenticate users belonging to an organization.
# Work with Tokens and Organizations
Your Auth0 plan or custom agreement affects whether this feature is available. To learn more, read [Pricing](https://auth0.com/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](/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, 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.
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).
### 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.
```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"
]
}
```
## 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.
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).
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, additional validation should be performed 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](/docs/manage-users/organizations/configure-organizations/use-org-name-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:
* 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
* [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)