---
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. For the `agent_end_user` role this is an agent alias key, which shares the same shape.
    - `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.

## Other responses

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

## Changes

- **2026-09-14** `c94fd099d78b` — 1 warning
  - added the new `metrics_viewer` enum value to the `api_roles/items/` response property for the response status `200`
- **2026-08-05** `fca567a46b3a` — 1 warning
  - added the new `agent_end_user` enum value to the `agent_roles/items/role` response property for the response status `200`

[Change history](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/changes/v2/agents/:agent_key/identity/get.md)

---

[API](https://skmtc.dev/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/revisions/4557c44ba062?raw)