Guides

API keys

Organization keys, test and live, what each may do and reach — and the older per-agent chat keys.

An API key belongs to your organization. Owners and admins make them on the console's API keys page; making one asks for your password again, and every owner is emailed.

Test and live

	Test key, `ag_test_…`	Live key, `ag_live_…`
Calls	Only test numbers. Nothing rings.	Real phones.
Conversations it reads	Test-key conversations only.	Real ones only.
Its events go to	Test receivers.	Live receivers.
From a browser	Yes — this site's Try it uses one.	Never: `403 live_key_in_browser`.

What a key may do

Permission	Lets it
`agents:read`	Read agents and their variables.
`phone_numbers:read`	List the organization's numbers.
`calls:write`	Place and end calls, and make test calls.
`chats:write`	Start and continue chats, upload pictures.
`conversations:read`	Read and sync conversations.
`transcripts:read`	Read what was said.
`recordings:read`	Get recording links. Never part of a preset: tick it on its own.

The presets — Read only, Outbound calling and Chat — are starting points. A key asking for something it may not do gets 403 permission_denied, naming the permission.

A key reaches every project, or only the projects you choose — and within them, if you like, only some agents. Anything outside is 404, exactly as if it did not exist. GET /v1/me says what a key is and what it reaches:

Check your key

#!/bin/sh
# Check your key
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/me" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

Where a key works from

A key can be limited to your servers' addresses when it is made: single addresses like 203.0.113.7, or ranges like 198.51.100.0/24, IPv4 or IPv6, up to 20. A request from anywhere else is refused with 403 address_not_allowed, and detail names the address it came from — the address your server is seen from, after any proxy of your own. A key made without addresses works from anywhere. reach.addresses in GET /v1/me lists them; they cannot be changed afterwards, so a server that moves needs a new key.

Rotating and revoking

Rotate a key that may have leaked, or when somebody who knew it leaves: it gets a new secret, and the old one keeps working for the time you choose — none, an hour, a day or a week — so your servers can be updated first. Revoke stops a key on its very next request. An organization can have 25 keys in use. A key whose maker has left the organization is flagged, never cancelled for you.

See what a key has been doing

Each key's Requests page in the console, in the key's menu under API keys, lists every request it made in the last 30 days: the method, the path, the status, the error code of a refusal, how long the answer took, and the request id. Use it to see why a request was refused. Request bodies are never kept.

If a key leaks

Rotate it, or revoke it, on the API keys page. If the key was pushed to a public repository on GitHub, it may already be revoked: GitHub's secret scanning recognises our keys by their shape, and reports them to us. A working key found that way is revoked within seconds — a rotated key's old secret just stops — and every owner of the organization is emailed with where it was found. Make a new key for the servers that used it, and remove the secret from the repository, history included.

The older chat keys

Before organization keys, each agent had its own secret key (ag_sk_…) on its Connect → Server API tab, for chatting with that one agent. Those keys keep working and can be rotated, but reach nothing else. Anything new should use an API key.