# REST API: authentication with an API key

Adresse: https://docs.athaus.ai/en/api/v1/anmeldung

> 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.

Type: Guide
Last updated: 2026-11-16

`/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](/en/api/schluessel).

```http
Authorization: Bearer ath_live_...
```

## Create a key [#create-a-key]

1. A member of the office opens [Settings, API-Keys](https://app.athaus.ai/einstellungen/api-keys).
2. 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.
3. They copy the key. **It is shown only once.**

What you should know:

* At `/v1` the 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, `/v1` answers `403` with `plan_required`.
* The [version](/en/api/v1/fassungen) 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](/en/api/v1/testmodus) with invented data, and nothing leaves it.
* A key in the form `ath_...` without `live` works 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](/en/api/schluessel).

## What does not work at /v1 [#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 [#scopes]

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](/en/api/v1/hinausgehen)). `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](/en/api/v1/hinausgehen#decide)). The MCP server for providers calls the first three `lesen`, `vorschlagen` and `freigeben` ([Rights](/en/mcp/rechte)); 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`.

```json
"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-verwalten]

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 [#what-can-go-wrong]

| Status | Code                                                                  | Cause                                                               |
| ------ | --------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `401`  | [`unauthorized`](/en/api/errors#unauthorized)                         | the key is missing, invalid or revoked, or its person has no office |
| `403`  | [`insufficient_permissions`](/en/api/errors#insufficient_permissions) | the key lacks the scope or the level on the resource                |
| `403`  | [`plan_required`](/en/api/errors#plan_required)                       | the plan of the office has no API access                            |
| `429`  | [`rate_limited`](/en/api/errors#rate_limited)                         | too many failed attempts from one address                           |
