# REST-API: Anmeldung mit einem API-Key

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

> Jeder Aufruf von /v1 trägt einen API-Key als Bearer-Token. Wo du ihn bekommst, welche Scopes er trägt und was nicht geht.

Typ: Anleitung
Zuletzt aktualisiert: 2026-11-16

`/v1` kennt genau einen Weg zur Anmeldung: einen API-Key im Kopf `Authorization`. Kein Cookie, kein Parameter in der Adresse, kein CORS. Diese Seite sagt, wie der Aufruf sich anmeldet; wie du einen Key anlegst und seine Scopes wählst, steht unter [API-Schlüssel](/api/schluessel).

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

## Einen Key anlegen [#einen-key-anlegen]

1. Ein Mitglied des Büros öffnet [Einstellungen, API-Keys](https://app.athaus.ai/einstellungen/api-keys).
2. Es gibt dem Key einen Namen und wählt seine Scopes. Ohne Wahl kann der Key nur lesen. Wer will, schränkt ihn je Ressource weiter ein.
3. Es kopiert den Key. **Er wird nur einmal gezeigt.**

Das solltest du wissen:

* Bei `/v1` handelt der Key für das Büro, zu dem er gehört. Wer ihn angelegt hat, spielt dafür keine Rolle.
* Verlässt die Person das Büro, endet ihr Key. Ein Key der Leitung bleibt beim Büro, bis die Leitung ihn widerruft.
* Gespeichert wird nur ein Hash. Wer den Key verliert, legt einen neuen an.
* Keys gibt es in Pro und Scale. In Basic antwortet `/v1` mit `403` und `plan_required`.
* Die [Version](/api/v1/fassungen) ist der Pfad, `v1`. Ein Key hängt an keiner Version.
* Wähle unter Key-Typ *Test*, und du bekommst einen Key `ath_test_...`. Er arbeitet im [Testbüro](/api/v1/testmodus) mit erfundenen Daten, und nichts verlässt es.
* Ein Key im Format `ath_...` ohne `live` gilt hier auch. Sie handeln für das Büro ihrer Person und nie mit mehr, als die Person darf.

Du prüfst einen Key jederzeit mit `GET /v1/me`. Mehr zum Anlegen und Widerrufen steht unter [API-Schlüssel](/api/schluessel).

## Was bei /v1 nicht geht [#was-bei-v1-nicht-geht]

| Zugriff                                           | Antwort                               |
| ------------------------------------------------- | ------------------------------------- |
| Sitzungs-Cookie der App                           | wird nicht gelesen, also `401`        |
| Kein Kopf, ein falscher oder ein widerrufener Key | `401` mit dem Kopf `WWW-Authenticate` |
| Key einer Person ohne Büro                        | `401`                                 |

Wer von einer Adresse innerhalb einer Minute mehr als 20 erfundene Keys schickt, bekommt `429`. Ein gültiger Key zählt dafür nie mit.

## Scopes und Stufen [#scopes]

Ein Key hat zwei Achsen.

**Wie weit: der Scope.** Es gibt drei, dazu einen vierten, der nur an `/v1` gilt. `read` liest. `propose` legt im Büro an, ändert und löscht und bereitet Nachrichten an Anfragende vor. `approve` lässt eine Nachricht hinausgehen, ohne dass eine Person Ja sagt ([Was das Büro verlässt](/api/v1/hinausgehen)). `decide` lässt den Key die Vorschläge freigeben und verwerfen, die er selbst angelegt hat, auch Mails an Kunden und Anfragende, ohne dass jemand sie vorher liest. Er setzt `approve` voraus, wird beim Anlegen eigens eingeschaltet und gilt nie für einen bestehenden Key ([Ohne Person entscheiden](/api/v1/hinausgehen#decide)). Der MCP-Server für Anbieter nennt die ersten drei `lesen`, `vorschlagen` und `freigeben` ([Rechte](/mcp/rechte)); `decide` gibt es dort nicht.

**Worauf: die Stufe.** Eine Stufe je Ressource: `none`, `read` oder `write`. Die Scopes setzen eine Vorlage, und wer den Key anlegt, kann sie einschränken, nie erweitern. Eine Operation braucht ihren Scope und mindestens die Stufe ihrer Ressource. Die Ressourcen sind `listings`, `contacts`, `inquiries`, `viewings`, `files`, `webhookEndpoints` und `apiKeys`.

```json
"permissions": { "listings": "read", "contacts": "none" }
```

Dieser Key sieht Inserate, und `/v1/contacts` antwortet mit `403` und `insufficient_permissions`. Zugriff auf `contacts`, `webhookEndpoints` und `apiKeys` bekommt nur ein Key, den die Leitung angelegt hat.

## Keys verwalten [#keys-verwalten]

Keys legst du in der App an, nie über die API: Ein Key, der Keys anlegt, wäre ein Geheimnis, das weitere Geheimnisse macht. `GET /v1/apiKeys` und `GET /v1/apiKeys/{id}` zeigen die Keys des Büros ohne das Geheimnis, nur mit Präfix, Scopes, Stufen und letzter Nutzung. `DELETE /v1/apiKeys/{id}` widerruft einen Key, auch den aufrufenden: Sein nächster Aufruf antwortet `401`. Das Protokoll des Büros zeigt es wie einen Widerruf in der App, mit dem Key (Name und Id) als Handelndem. Das Widerrufen ist wie in der App auf fünf in kurzer Folge und dann einen alle 20 Sekunden je Key begrenzt.

`apiKeys` ist die Ressource, die ein Key nie von selbst hat: Sie ist `none`, bis die Leitung sie beim Anlegen in der App wählt, und Keys von vor dem 16. November 2026 haben sie nicht. Ein Live-Key sieht und widerruft nur Live-Keys, ein Test-Key nur Test-Keys. Ein Key eines anderen Büros und ein Key der anderen Art antworten `404`.

## Was schiefgehen kann [#was-schiefgehen-kann]

| Status | Code                                                               | Ursache                                                                      |
| ------ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| `401`  | [`unauthorized`](/api/errors#unauthorized)                         | der Key fehlt, ist ungültig oder widerrufen, oder seine Person hat kein Büro |
| `403`  | [`insufficient_permissions`](/api/errors#insufficient_permissions) | dem Key fehlt der Scope oder die Stufe auf der Ressource                     |
| `403`  | [`plan_required`](/api/errors#plan_required)                       | der Tarif des Büros hat keinen API-Zugang                                    |
| `429`  | [`rate_limited`](/api/errors#rate_limited)                         | zu viele Fehlversuche von einer Adresse                                      |
