Register an Agent

Register an agent as a first-class identity in Auth0 using the Auth0 Dashboard or Management API. Once registered, you can manage the agent with the Management API using the standard CRUD operations.

Create and register a new agent

Create and register a new agent with the Auth0 Dashboard and Management API.

Auth0 Dashboard
Management API

Navigate to Dashboard > Agents and select Create New Agent.
Enter a name for the agent.
Select Create.

Once successfully created, the agent should have a unique agent_id with the agt_ prefix. To view the agent’s details, select View Details.

First, make sure your Management API access token has the create:agents permission.Then, make a POST request to /api/v2/agents with the following parameters:

curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/agents' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_MGMT_API_TOKEN' \
  --data '{
    "name": "recommendation-agent-prod",
    "external_agent_id": "my-org-agent-042",
    "metadata": {
      "env": "prod",
      "team": "personalization"
    }
  }'

Field	Required	Description
`name`	Yes	1–255 characters.
`client_id`	No	Associate an existing client on agent creation.
`external_agent_id`	No	Can only be set at creation time. You cannot modify afterward. To learn more, read `external_agent_id`.
`metadata`	No	JSON, limit 10 KB.

Do not include personally identifiable information (PII) in the name or metadata fields. These values are recorded in logs and may be visible to administrators and log streaming destinations.

If successful, Auth0 returns an agent object like the following:

{
    "agent_id": "agt_sJsP2T4rLopMQMWz2eEGmW",
    "name": "recommendation-agent-prod",
    "metadata": {
        "env": "prod",
        "team": "personalization"
    },
    "created_at": "2026-07-28T21:40:01.395Z",
    "updated_at": "2026-07-28T21:40:01.395Z",
    "external_agent_id": "my-org-agent-042"
}

Agent object

Once registered, Auth0 stores the agent with the following object schema:

Field	Type	Description
`agent_id`	string	Server-generated. Format: `agt_` + 22 base58 characters. Not modifiable. Always used to address the agent via the Management API, even when `external_agent_id` is set.
`external_agent_id`	string	Optional. Customer-supplied identifier. Must be set at creation; it cannot be added or changed afterward. When set, it replaces `agent_id` in token claims and tenant logs.
`name`	string	1–255 characters. Required on creation.
`metadata`	object	JSON, limit 10 KB.
`created_at`	string	ISO 8601 timestamp.
`updated_at`	string	ISO 8601 timestamp.

The agent object is returned by all /api/v2/agents endpoints.

`external_agent_id`

You can supply your own identifier for an agent using external_agent_id, so that the agent identity visible in tokens and logs matches an ID already in use in your own systems. You must specify the external_agent_id at agent creation; it cannot be added or changed afterward. When set, the external_agent_id replaces agent_id wherever the agent’s identity appears in issued tokens (sub, act.sub) and in tenant logs. 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.

Do not include personally identifiable information (PII) in external_agent_id. This value is recorded in logs and may be visible to administrators and log streaming destinations.

Next steps

Associate agent with a client to issue tokens with agent identity

Get Started

Reference

Create and register a new agent

Agent object

`external_agent_id`

Next steps

​Create and register a new agent

​Agent object

​external_agent_id

​Next steps

Create and register a new agent

Agent object

`external_agent_id`

Next steps