Create an API key and choose its scopes
An API key for the REST API, your own agents and services, with exactly the scopes you give it.
Last updated:
An API key gives your system or agent exactly the scopes you give it. Here you create it. How a call to /v1 signs in with the key is under Authentication.
Create a key
- Open Settings, API-Keys.
- Give it a name and choose the scopes:
readis always included,proposeandapproveonly if the agent needs them. If you like, narrow the key per resource. - Copy the key (
ath_live_...). It is shown only once.
Under Key type you choose Live or Test. A test key (ath_test_...) is listed alongside the others but works in the test office with invented data, nothing leaves it, and it works at the REST API only. It checks the plan of the real office like any key.
Send it as Authorization: Bearer ath_live_... (Authentication). A live key works everywhere: at the REST API, at the MCP server and for your own agents. A test key works at the REST API only.
What you need to know
- Only a fingerprint is stored; if you lose the key, create a new one.
- Every member creates keys and revokes their own. The management sees and revokes every key of the office. Revoking takes effect immediately.
- At the REST API the key acts for the office. At the MCP server and for your own agents it acts as the person who created it, with that person's role and at most the scopes of the key.
- When a member leaves the office, their keys end. Keys of the management stay with the office and then act as the owner.
- A key can never do more than the person who creates it: access to
contacts,webhookEndpointsandapiKeysat the REST API exists only with a key from the management. - A key you narrow per resource works only at the REST API. At the MCP server and for your own agents it answers
schluessel_nur_v1. - Keys exist in Pro and Scale; in Basic the API answers
plan_required. - A key in the form
ath_...withoutlivealso works at the REST API and appears in the same list.
Which scopes
At the REST API the three scopes are read, propose and approve (Scopes and levels). The MCP server calls the same three lesen, vorschlagen and freigeben (Rights).
| REST API | MCP server | At the REST API | On Athaus für Anbieter |
|---|---|---|---|
read | lesen | every read call | every read tool |
propose | vorschlagen | write calls; preparing messages | drafts, suggestions, valuations |
approve | freigeben | a message goes out without a yes when the automation of the office allows it | decide on suggestions; Automatic runs without a click |
Give only what the agent needs: one that drafts replies needs propose without approve, then every draft waits for your yes.
Keep reading
REST API: authentication with an API key
Every call to /v1 carries an API key as a bearer token. Where to get one, which scopes it carries and what does not work.
MCP rights: what an agent may do
Three rights per server, independent of each other, and the rule for when a click is needed. In OAuth the rights are the scopes, under the same names.
API error codes: what each code means
Every code the REST API returns in the member code of a problem, with its HTTP status and meaning. Generated from the contract.