Agent identities
Updated
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?
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 describes.