API reference
Keys and scopes
The six kinds of Agentower key, what each can do, and how to create, store and revoke them.
Every API request carries a key. A key belongs to one workspace and to the person who made it, and has exactly one scope.
#The six scopes
| Scope | Made on | Can | Can't |
|---|---|---|---|
ingest | Keys & connections → 1 · Create an ingest key | Report agents: events, hooks, telemetry, plan limits, asks, guardrail checks, import | Read anything back beyond its own asks and guard checks |
telemetry | Keys & connections → step 4 (tokens and cost) → Create a telemetry key | Send OpenTelemetry only: POST /v1/logs, /v1/metrics, /v1/traces | Report hook events, poll asks, read answers, or anything else — refused on every other route |
public:read | Keys & connections → open Public stats (owners) | Read the counters the workspace chose to publish (GET /v1/stats) | Read agents, report, approve or anything else |
mcp | Keys & connections → open MCP server → Create MCP key | Use the MCP server: list and look up agents, export data, report a status | Approve, deny or reply to agents |
export:read | History → Export → Create export key | Read the export API, limited to what its creator's role may see | Report or change anything |
agents:act | Keys & connections → open Agent actions API → Create agent-actions key (owners and approvers, signed in within 7 days) | List open agents; message, allow or deny, take back a message, let an agent past a guardrail — only on projects its creator may approve. Expires after 30 days | Anything its creator couldn't do in the app |
A telemetry key is the one to put in Claude Code's settings (the OTEL_EXPORTER_OTLP_HEADERS line): commands an agent runs can read that file, so a key there should be able to do as little as possible. Anyone in the team can make one, like an ingest key, with no recent sign-in needed. Create one on Keys & connections (step 4, Create a telemetry key); the settings block shown there then uses it. Once you have one, the ~/.agentower/claude-code.env snippet there also carries an AGENTOWER_TELEMETRY_TOKEN line, and the settings env block sets OTEL_LOGS_EXPORT_INTERVAL and OTEL_METRIC_EXPORT_INTERVAL to 60000 (once a minute). The Claude Code setup command (node scripts/claude-code.mjs connect) uses AGENTOWER_TELEMETRY_TOKEN from that file, with the same two intervals, and otherwise falls back to your ingest key with a warning. The Agentower plugin doesn't set up telemetry. An ingest key still works for OpenTelemetry — see OpenTelemetry.
Only an agents:act key can act on agents — see Agent actions API. Every other key is limited to reporting or reading.
#Who the agents belong to
Agents reported with an ingest key are shown as the key's creator's. That's why each person makes their own keys for their own machines.
Export and agent-actions keys follow their creator's current role: if an approver becomes a viewer, their export key loses the audit log and their agent-actions key can no longer act. When someone is removed from a team, or deletes their account, their keys are revoked.
#What a key looks like
at_live_Xq3… (production)
at_test_Xq3… (staging and local development)at_live_ or at_test_, then 32 letters and digits. A key from one environment never works in another.
#Creating and storing keys
- A key is shown once, when it's made. Agentower keeps only a SHA-256 fingerprint of it, so it can't be shown again — make a new one if it's lost.
- Store keys like passwords: in a file only you can read (
chmod 600), a secrets manager, or your server's environment. Never in a web page, a public repository or a shared chat. - Use one ingest key per machine, so you can revoke one laptop without touching the others.
- A workspace can have up to 20 active keys in total. Owners can make any of them; everyone else can hold at most 5 active keys of their own.
#Revoking keys
Press Revoke next to the key. It stops working within a minute (keys are checked against a short cache), and a channel opened with it is closed at once. Creating and revoking keys is recorded in the audit log.
#Last used
Each key shows when it was last used, updated at most every 10 minutes. "Not used yet" after you've connected a tool means requests with that key aren't arriving — see Troubleshooting.