By default, the Authentication API uses organization IDs to identify specific organizations. If needed, you can configure your tenant to also use organization names as an identifier. However, there are usability and security implications to consider before enabling this feature. To better understand the potential impact, review the Considerations and recommendations section.

​
How it works

Configuring your tenant to support organization names in the Authentication API results in the following:
  • The organization parameter in the /authorize and SAML endpoints can accept both organization names and IDs.
  • Access and automatically include both org_name and org_id claims.
  • Organizations can be configured with two names: a required Name value that serves as a unique logical identifier and an optional, user-friendly Display Name. The org_name parameter only accepts the required Name value and does not support Display Name values.
  • This feature is managed at the tenant level. It cannot be individually enabled for specific organizations.
You can enable this feature through your or the :
  • Auth0 Dashboard: Select Settings from the left-side menu and choose the Advanced tab. In the Settings section, enable the Allow Organization Names in Authentication API toggle.
  • Management API: Use the PATCH /api/v2/tenants/settings endpoint to set allow_organization_name_in_authentication_api to true. For more information, review the Management API documentation.

​
Example flow

The following example demonstrates an authorization code flow that uses organization names.
  1. Call the /authorize endpoint passing your organization name for the organization parameter:
https://{yourDomain}/authorize?
    response_type=code&
    client_id={yourClientId}&
    redirect_uri={https://yourApp/callback}&
    scope={scope}&
    state={state}&
    organization={yourOrganizationName}
  1. After obtaining the authorization code, call the POST /oauth/token endpoint to retrieve access and ID tokens:
curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data 'client_id={yourClientId}' \
  --data 'client_secret={yourClientSecret}' \
  --data 'code=yourAuthorizationCode}' \
  --data 'redirect_uri={https://yourApp/callback}'
  1. The decoded tokens returned contain both the org_id and org_name claims:
{
    "sub": "google-oauth2|10...17",
    "aud": [
        "https://yourApp"
    ],
    "iat": 1686840988,
    "exp": 1686927388,
    "azp": "Suo...qTd",
    "scope": "openid profile",
    "org_id": "{yourOrganizationId}",
    "org_name": "{yourOrganizationName}"
}

​
Considerations and recommendations

Before using organization names in the Authentication API, it is important to understand the primary differences between organization names and IDs. Unlike organization IDs (which remain static), you can change the name of an organization at any time after initial creation. Additionally, you can reuse organization names within a single tenant as long as it’s only assigned to exactly one organization at a time. In practice, this means you can change the name of one of your organizations and reuse its original name for another organization in your tenant. Organization names are only unique within a single tenant; the same name may be used for two or more organizations across multiple tenants. In general, using organization IDs is recommended when validating tokens. However, if using organization names is more appropriate for your use case, consider the implications below when implementing the feature.

​
Usability and security considerations

Consider the potential impacts below when using organization names to request and validate tokens:
  • Organization names can be reused: Long-lived tokens do not expire when an organization changes its name, and the org_name claims in those tokens retain their original value. If the original name is later reused by a different organization, such tokens may grant users unauthorized access to data and resources managed by the new organization.
  • Organization names are only unique within a single tenant: If your API does not verify iss (issuer) claims in tokens, an organization with the same name in a different tenant could generate tokens that are incorrectly accepted by your API.
  • Organization names can be changed: If you change the name of an organization, your applications must provide the new organization name in Authentication API requests. As tokens can be long-lived, the org_name claim in a token may no longer match the current organization name, which could prevent applications from granting access to the appropriate organization.
Due to the possible security and usability impacts, using IDs instead of names to validate tokens is recommended when working with organizations. If you choose to use organization names, follow the best practices below for an optimal experience:
  • Always validate the iss claim to ensure a token was issued by your Auth0 tenant.
  • Avoid reusing organization names that previously existed in your tenant. To prevent reuse and ensure previously issued tokens cannot be used to access different organizations, maintain an accurate and up-to-date record of historic organization names.
  • Avoid renaming organizations once they are in use unless absolutely necessary. If you choose to rename an organization, be aware that existing access and ID tokens do not automatically contain the new organization name. After renaming an organization, ensure you prompt users to log in again.