---
title: "Get agent identity"
method: GET
path: "/v2/agents/{agent_key}/identity"
tags: ["Agent Identity"]
---

# Get agent identity

`GET /v2/agents/{agent_key}/identity`

Returns the identity associated with an agent. The identity is the service account the agent uses when executing tools.

In `auto` mode (the default), the platform keeps the identity's roles in sync with the agent's tool configuration.

In `manual` mode, the roles are frozen. The platform does not modify them when the agent is updated.

## Path parameters

- `agent_key` string, required — A unique key that identifies an agent.

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Response `200`

The agent's identity details.

- AgentIdentity — The identity associated with an agent, including its roles and management mode.
  - `mode` 'auto' | 'manual', required — The role management mode of the agent's identity. - `auto`: The platform keeps roles in sync with the agent's tool configuration. When tools change, the platform recomputes roles automatically. - `manual`: The caller manages the roles. The platform does not modify roles when the agent is updated.
  - `client_id` string, required — The OAuth2 client ID of the agent's service account.
  - `api_roles` ApiRole[], required — Customer-level roles assigned to this identity.
  - `corpus_roles` CorpusRole[], required — Corpus-specific role assignments for this identity.
    - `corpus_key` string, required — The key of the corpus this role applies to.
    - `role` 'owner' | 'administrator' | 'viewer' | 'editor', required — The role assigned for this specific corpus.
  - `agent_roles` AgentRole[], required — Agent-specific role assignments for this identity.
    - `agent_key` string, required — The key of the agent this role applies to.
    - `role` 'agent_administrator' | 'agent_viewer' | 'agent_developer' | 'agent_user' | 'agent_end_user', required — The role assigned for this specific agent. * `agent_administrator` - Full administrative access to the agent including deletion and configuration. * `agent_viewer` - Read-only access to view agent configuration, sessions, events, instructions, and tools. * `agent_developer` - Can modify agent configuration, create/manage sessions, update tools and instructions. * `agent_user` - Limited access to interact with the agent by creating sessions and sending inputs. Cannot view agent configuration or modify settings. * `agent_end_user` - Granted on an alias, lets a user create sessions and send messages through it. They see only their own sessions, and within them only their own messages and the agent's replies. This must be the only role the user holds. The platform rejects assigning it alongside any other role.

## Other responses

- `403` — Permissions do not allow accessing this agent.
- `404` — Agent not found.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/revisions/e85040b266cc/schema)