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.
Last updated:
/v1 knows exactly one way to sign in: an API key in the Authorization header. No cookie, no parameter in the address, no CORS. This page says how a call signs in; how to create a key and choose its scopes is under API keys.
Authorization: Bearer ath_live_...Create a key
- A member of the office opens Settings, API-Keys.
- They give the key a name and choose its scopes. Without a choice the key can only read. If they like, they narrow it per resource.
- They copy the key. It is shown only once.
What you should know:
- At
/v1the key acts for the office it belongs to. Who created it does not matter for that. - When the person leaves the office, their key ends. A key of the management stays with the office until the management revokes it.
- Only a hash is stored. Whoever loses the key creates a new one.
- Keys exist in Pro and Scale. In Basic,
/v1answers403withplan_required. - The version is the path,
v1. A key depends on no version. - Choose Test under key type and you get an
ath_test_...key. It works in the test office with invented data, and nothing leaves it. - A key in the form
ath_...withoutliveworks here too. They act for their person's office and never with more than the person may do.
You can check a key at any time with GET /v1/me. More on creating and revoking is under API keys.
What does not work at /v1
| Access | Answer |
|---|---|
| Session cookie of the app | not read, so 401 |
| No header, a wrong or a revoked key | 401 with the header WWW-Authenticate |
| Key of a person without an office | 401 |
Whoever sends more than 20 invented keys from one address within a minute gets 429. A valid key never counts towards this.
Scopes and levels
A key has two axes.
How far: the scope. There are three, plus a fourth that applies only at /v1. read reads. propose creates, changes and deletes in the office, and prepares messages to people who inquired. approve lets a message go out without a person saying yes (What leaves the office). decide lets the key approve and reject the proposals it created itself, including mails to customers and inquirers, before anyone has read them. It needs approve, is switched on separately when the key is created and never applies to an existing key (Deciding without a person). The MCP server for providers calls the first three lesen, vorschlagen and freigeben (Rights); it has no decide.
On what: the level. One level per resource: none, read or write. The scopes set a template, and whoever creates the key can narrow it, never widen it. An operation needs its scope and at least the level of its resource. The resources are listings, contacts, inquiries, viewings, files, webhookEndpoints and apiKeys.
"permissions": { "listings": "read", "contacts": "none" }This key sees listings, and /v1/contacts answers 403 with insufficient_permissions. Only a key created by the management gets access to contacts, webhookEndpoints and apiKeys.
Manage keys
Keys are created in the app, never through the API: a key that creates keys would be a secret that makes more secrets. GET /v1/apiKeys and GET /v1/apiKeys/{id} show the keys of the office without the secret, only with prefix, scopes, levels and last use. DELETE /v1/apiKeys/{id} revokes a key, the calling key included: its next call answers 401. The history of the office shows it like a revocation in the app, with the key (name and id) as the actor. Revoking is limited like the app: five in a burst, then one every 20 seconds per key.
apiKeys is the resource a key never has by itself: it is none until the management picks it when creating the key in the app, and keys from before 16 November 2026 do not have it. A live key sees and revokes live keys only, a test key test keys only. A key of another office and a key of the other mode answer 404.
What can go wrong
| Status | Code | Cause |
|---|---|---|
401 | unauthorized | the key is missing, invalid or revoked, or its person has no office |
403 | insufficient_permissions | the key lacks the scope or the level on the resource |
403 | plan_required | the plan of the office has no API access |
429 | rate_limited | too many failed attempts from one address |
Keep reading
REST API: the first call
The REST API reads and writes the listings, contacts, inquiries, viewings and files of your office. One key, one call, JSON back.
REST API: errors as problem details
Every error from /v1 is an RFC 9457 problem with a real HTTP status, a code to branch on and a request id for support.
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.