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

# Associate an Agent with a Client

> Associate one or more clients with an agent so that tokens issued to those clients carry the agent's identity for attribution and traceability.

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

<ReleaseStageNotice feature="Agents as Principal" stage="ea" contact="Auth0 Support" terms="true" />

Once [registered as a first-class identity in Auth0](/docs/ai-agents-mcp/agents-as-principal/register-an-agent), you can associate an agent with any OAuth client. An agent can be associated with multiple clients. This is useful when you want one logical agent identity with a single `agent_id` visible in tokens and logs across multiple clients, such as separate clients per environment or region.

The `agent_id` is stored on the client object, and associations are managed dynamically.

Once you associate an agent with a client, tokens issued to that client carry the agent's identity as the subject (`sub`) for client credentials grants, or as the actor (`act`) for token exchange and standard login flows. To learn more, read [Agent Identity in Tokens](/docs/ai-agents-mcp/agents-as-principal/agent-identity-in-tokens).

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  The internal `agent_id` remains the identifier used to manage the agent through the Management API, regardless of whether you've set an `external_agent_id`.
</Callout>

## Associate a client at creation

Set the `agent_id` when creating a client via `POST /api/v2/clients`:

```bash theme={null}
curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/clients' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_MGMT_API_TOKEN' \
  --data '{
    "name": "My AI Client",
    "agent_id": "YOUR_AGENT_ID"
  }'
```

If successful, Auth0 returns the client object with the `agent_id` you set.

## Retrieve the agent-associated client

Once you've associated an `agent_id` with a client, make a `GET` request to `/api/v2/clients/{id}` to return the client object:

```bash theme={null}
curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/clients/YOUR_CLIENT_ID' \
  --header 'Authorization: Bearer YOUR_MGMT_API_TOKEN'
```

If successful, Auth0 returns the client object with the `agent_id` you set.

## Associate an existing client

You can associate an existing client using the Auth0 Dashboard or Management API.

<Tabs>
  <Tab title="Auth0 Dashboard">
    1. Navigate to **Dashboard > Agents**, select the agent, and then the agent's **Applications** tab.
    2. Select **Add Application** and select the applications you want to associate with the agent in the modal. You can select multiple applications.
    3. Select **Add Applications**.

    Once successfully added, the applications appear under the **Applications** tab for the agent.
  </Tab>

  <Tab title="Management API">
    Associate an existing client with an agent via `PATCH /api/v2/clients/{id}`:

    ```bash theme={null}
    curl --request PATCH \
      --url 'https://YOUR_AUTH0_DOMAIN/api/v2/clients/YOUR_CLIENT_ID' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer YOUR_MGMT_API_TOKEN' \
      --data '{
        "agent_id": "YOUR_AGENT_ID"
      }'
    ```

    If successful, Auth0 returns the updated client object with the `agent_id` you set.
  </Tab>
</Tabs>

## Remove the agent association

To dissociate a client from its agent, set `agent_id` to `null` via `PATCH /api/v2/clients/{id}`:

```bash theme={null}
curl --request PATCH \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/clients/YOUR_CLIENT_ID' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_MGMT_API_TOKEN' \
  --data '{
    "agent_id": null
  }'
```

After dissociation, new tokens issued to the client no longer carry agent identity. Existing tokens remain valid until expiry.

## Next steps

* Learn about how Auth0 embeds [agent identity in tokens](/docs/ai-agents-mcp/agents-as-principal/agent-identity-in-tokens)