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

> Setup, security considerations, and best practices for using organization names in the Authentication API.

# Use Organization Names in Authentication API

export const AuthCodeBlock = ({filename, icon, language, highlight, children}) => {
  const [displayText, setDisplayText] = useState(children);
  const [copyText, setCopyText] = useState(children);
  const wrapperRef = React.useRef(null);
  useEffect(() => {
    let unsubscribe = null;
    function init() {
      if (!window.autorun || !window.rootStore) {
        return;
      }
      unsubscribe = window.autorun(() => {
        let processedChildrenForDisplay = children;
        let processedChildrenForCopy = children;
        for (const [key, value] of window.rootStore.variableStore.values.entries()) {
          const escapedKey = key.replaceAll(/[.*+?^${}()|[\]\\]/g, (String.raw)`\$&`);
          let displayValue = value;
          if (key === "{yourClientSecret}" && value !== "{yourClientSecret}") {
            displayValue = value.substring(0, 3) + "*****MASKED*****";
          }
          processedChildrenForDisplay = processedChildrenForDisplay.replaceAll(new RegExp(escapedKey, "g"), displayValue);
          processedChildrenForCopy = processedChildrenForCopy.replaceAll(new RegExp(escapedKey, "g"), value);
        }
        setDisplayText(processedChildrenForDisplay);
        setCopyText(processedChildrenForCopy);
      });
    }
    if (window.rootStore) {
      init();
    } else {
      window.addEventListener("adu:storeReady", init);
    }
    return () => {
      window.removeEventListener("adu:storeReady", init);
      unsubscribe?.();
    };
  }, [children]);
  useEffect(() => {
    if (!wrapperRef.current) return;
    const originalWriteText = navigator.clipboard.writeText.bind(navigator.clipboard);
    let isOverriding = false;
    const handleClick = e => {
      const button = e.target.closest('[data-testid="copy-code-button"]');
      if (!button || !wrapperRef.current.contains(button)) return;
      isOverriding = true;
      navigator.clipboard.writeText = text => {
        if (isOverriding) {
          isOverriding = false;
          navigator.clipboard.writeText = originalWriteText;
          return originalWriteText(copyText);
        }
        return originalWriteText(text);
      };
      setTimeout(() => {
        if (isOverriding) {
          isOverriding = false;
          navigator.clipboard.writeText = originalWriteText;
        }
      }, 100);
    };
    const wrapper = wrapperRef.current;
    wrapper.addEventListener('click', handleClick, true);
    return () => {
      wrapper.removeEventListener('click', handleClick, true);
      if (navigator.clipboard.writeText !== originalWriteText) {
        navigator.clipboard.writeText = originalWriteText;
      }
    };
  }, [copyText]);
  return <div ref={wrapperRef}>
      <CodeBlock filename={filename} icon={icon} language={language} lines highlight={highlight}>
        {displayText}
      </CodeBlock>
    </div>;
};

By default, the [Authentication API](https://auth0.com/docs/api/authentication) 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](#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](https://auth0.com/docs/api/authentication#authorize-application) and [SAML](https://auth0.com/docs/api/authentication#saml) endpoints can accept both organization names and IDs.
* Access and <Tooltip tip="ID Token: Credential meant for the client itself, rather than for accessing a resource." cta="View Glossary" href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip> automatically include both `org_name` and `org_id` claims.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  - [Organizations](/docs/manage-users/organizations/configure-organizations/create-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.
</Callout>

You can enable this feature through your <Tooltip tip="Auth0 Dashboard: Auth0's main product to configure your services." cta="View Glossary" href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip tip="Auth0 Dashboard: Auth0's main product to configure your services." cta="View Glossary" href="/docs/glossary?term=Management+API">Management API</Tooltip>:

* **Auth0 Dashboard**: Select [Settings](/docs/get-started/tenant-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](https://auth0.com/docs/api/management/v2) 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:

export const codeExample1 = `https://{yourDomain}/authorize?
    response_type=code&
    client_id={yourClientId}&
    redirect_uri={https://yourApp/callback}&
    scope={scope}&
    state={state}&
    organization={yourOrganizationName}`;

<AuthCodeBlock children={codeExample1} language="http" />

2. After obtaining the authorization code, call the `POST /oauth/token` endpoint to retrieve access and ID tokens:

export const codeExample2 = `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}'`;

<AuthCodeBlock children={codeExample2} language="bash" />

3. The decoded tokens returned contain both the `org_id` and `org_name` claims:

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

### Recommended best practices

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.