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

# Identities

> An identity represents an AI agent in Devctrl. It carries credentials, labels, and optional tool restrictions.

An identity represents a single AI agent (or agent instance) in your project. It's how the gateway knows who is making a request and what metadata to attach to policy evaluations.

## What's in an identity

| Field             | Purpose                                                                                 |
| ----------------- | --------------------------------------------------------------------------------------- |
| **Name**          | A human-readable name for the agent (e.g., `support-agent`, `ci-bot`)                   |
| **Labels**        | Key-value metadata used in policy evaluation (e.g., `team: support`, `env: production`) |
| **Credential**    | A secret token the agent uses to authenticate with the gateway                          |
| **Allowed tools** | An optional list restricting which tools this identity can see and call                 |

## Credentials

Each identity has a credential — a secret string the agent uses to authenticate with the gateway. MCP clients include it as a bearer token in the `Authorization` header:

```
Authorization: Bearer dc_live_a1b2c3d4e5f6...
```

Credentials are:

* **Securely stored** — credentials are hashed and never stored in plaintext
* **Single-use display** — the secret is shown once when created, then never again
* **Revocable** — you can revoke a credential at any time from the console
* **Expirable** — optionally set an expiration date

<Warning>
  Store credentials securely. If lost, generate a new credential — the old secret cannot be retrieved.
</Warning>

## Labels

Labels are key-value pairs attached to an identity. They're available in policy evaluation as `identity.labels`.

```cel theme={null}
// Only allow agents on the engineering team to deploy
identity.labels.team == "engineering"
```

Common label patterns:

* `team: support` / `team: engineering` / `team: data`
* `env: production` / `env: staging`
* `role: agent` / `role: service`
* `vendor: openai` / `vendor: anthropic`

Labels are flexible — use whatever makes sense for your policy structure.

## Allowed tools

By default, an identity can see all tools registered in the project. You can restrict this by setting an **allowed tools** list.

| Configuration                                 | Behavior                                               |
| --------------------------------------------- | ------------------------------------------------------ |
| Not set (null)                                | Identity can see and call **all** tools in the project |
| Empty list `[]`                               | Identity can see **no** tools                          |
| Specific tools `["get_issue", "list_issues"]` | Identity can only see and call these tools             |

<Note>
  Task-level allowed tools override identity-level restrictions. If a task defines its own tool list, it takes priority.
</Note>

## Identity in policy context

During policy evaluation, the identity is available as:

```json theme={null}
{
  "identity": {
    "name": "support-agent",
    "labels": {
      "team": "support",
      "role": "agent",
      "env": "production"
    }
  }
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="Create identities" icon="plus" href="/console/create-identities">
    Step-by-step guide to creating identities in the console.
  </Card>

  <Card title="Tasks" icon="list-check" href="/concepts/tasks">
    Learn how tasks add scoped context on top of identities.
  </Card>
</CardGroup>