# Agent identities

> Each agent is a named principal with its own key. Scopes it cannot widen, a budget it cannot raise. Disabling an agent revokes its keys at once.

Page: https://faxforagents.com/docs/agents/
Last changed: 2026-10-28

Updated Oct 28, 2026

An agent identity is a named principal with its own key, its own scopes and its own budget. Its actions are audited as `agent:<id>`. Disabling it revokes its keys in the same transaction.

## How do I register an agent?

Shell

```
`curl -s $FFA/agents -H "Authorization: Bearer $FFA_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "orders desk", "purpose": "confirm purchase orders", "contact_email": "ops@example.com", "policy_ids": ["pol_..."]}' curl -s $FFA/agents/agent_.../keys -H "Authorization: Bearer $FFA_KEY" \ -H "Content-Type: application/json" -d '{"label": "orders desk key"}'`
```

Scope `agent:admin` for the agent and `key:admin` for the key. The purpose is shown to people and never evaluated. The key is shown once.

## Which scopes can an agent have?

An API key carries a set of scopes. The default set reads and sends.

- Faxes: `fax:send`, `fax:quote`, `fax:read`, `fax:cancel`
- Documents: `document:read`, `document:write`
- Reads: `inbox:read`, `billing:read`, `approval:read`, `policy:read`, `account:read`
- Requests: `approval:request`, `sandbox:write`

A read-only key is the default set minus the write and send scopes.

An agent key is never issued `approval:decide`, `key:admin`, `policy:admin`, `agent:admin`, `billing:write` or `webhook:admin`. Asking for one is refused, not trimmed. Every route that does those things also refuses any principal with an agent id. An API key minted by hand with every scope still cannot.

## How are keys created, rotated and revoked?

`POST /v1/api-keys` creates a key. `POST /v1/api-keys/{id}/rotate` returns a new secret and keeps the old one working for 24 hours. `DELETE` revokes at once. Keys are stored as a peppered HMAC, so a database dump does not leak them. A test key is tied to the sandbox and the test wallet.

## What does the activity trail show?

`GET /v1/agents/{id}/activity` is the agent's audit trail: every row it caused, every row about it, metadata only. Pair it with a budget on the agent and a policy bound to it, and you have the three controls the [agents page](https://faxforagents.com/fax-for-ai-agents/) describes.

## From the blog

- [Why AI agents still need fax, and how to keep them safe](https://faxforagents.com/blog/why-ai-agents-need-fax/)