---
title: "Give an agent its own API key in one call"
method: POST
path: "/api/agents/identity/{slug}/tokens"
tags: ["API Tokens"]
---

# Give an agent its own API key in one call

`POST /api/agents/identity/{slug}/tokens`

## Request

- Base URL: `https://domani.run`
- URL: `https://domani.run/api/agents/identity/{slug}/tokens`
- Auth: HTTP bearer

Creates a token bound to this agent identity, confined to the mailboxes the agent operates, with the minimal scopes an agent needs (assistant:read, assistant:write, email:read, email:write). With that key the agent reads only its own Today, its mailboxes and the items handed to it; naming another agent answers 403 and owner-only routes (settings, backfill, export) refuse it. The full key is returned only in this response. Requires `tokens:write`. An agent that operates no mailbox gets no mail scopes by default, and asking for them answers 400 AGENT_MAILBOXES_REQUIRED: a key with no mailboxes would reach every mailbox of the account.

## Path parameters

- `slug` string, required

## Request body

- object
  - `name` string: Defaults to '<slug> agent'.
  - `scopes` string[]: Defaults to assistant:read, assistant:write, email:read, email:write. Cannot exceed the caller's own scopes.
  - `mailboxes` string[]: Mailbox addresses the token is confined to. Defaults to the mailboxes the agent operates.
  - `expires_in` integer: Seconds until expiry (max one year).

## Response `201`

Token created; the key is shown once

- object
  - `success` boolean
  - `token` object
    - `id` string
    - `name` string
    - `key` string
    - `scopes` string[]
    - `mailbox_ids` string[]
    - `expires_at` string, nullable
    - `agent_identity` object, nullable
      - `id` string
      - `name` string, nullable
      - `slug` string
  - `agent` object
    - `slug` string
    - `name` string, nullable
  - `hint` string

## Other responses

- `400`: Invalid request, or mail scopes asked for an agent that operates no mailbox (AGENT_MAILBOXES_REQUIRED)
- `401`: Missing or invalid API key
- `403`: Scope escalation or an agent-bound caller minting for another agent
- `404`: No such agent identity on this account
- `429`: Rate limit exceeded - wait and retry

---

[API](https://skmtc.dev/domani/apis/domani-run-api.md) · [All operations](https://skmtc.dev/domani/apis/domani-run-api/llms.txt) · [OpenAPI document](https://skmtc.dev/domani/apis/domani-run-api/revisions/7679f8159533?raw)