REST-API: Anmeldung mit einem API-Key
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.
Zuletzt aktualisiert:
/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.
Authorization: Bearer ath_live_...Einen Key anlegen
- Ein Mitglied des Büros öffnet Einstellungen, API-Keys.
- 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.
- Es kopiert den Key. Er wird nur einmal gezeigt.
Das solltest du wissen:
- Bei
/v1handelt 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
/v1mit403undplan_required. - Die Version 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 mit erfundenen Daten, und nichts verlässt es. - Ein Key im Format
ath_...ohnelivegilt 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.
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
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). 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). Der MCP-Server für Anbieter nennt die ersten drei lesen, vorschlagen und freigeben (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.
"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 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
| Status | Code | Ursache |
|---|---|---|
401 | unauthorized | der Key fehlt, ist ungültig oder widerrufen, oder seine Person hat kein Büro |
403 | insufficient_permissions | dem Key fehlt der Scope oder die Stufe auf der Ressource |
403 | plan_required | der Tarif des Büros hat keinen API-Zugang |
429 | rate_limited | zu viele Fehlversuche von einer Adresse |
Weiter lesen
REST-API: der erste Aufruf
Die REST-API liest und schreibt Inserate, Kontakte, Anfragen, Besichtigungen und Dateien deines Büros. Ein Key, ein Aufruf, JSON zurück.
REST-API: Fehler als Problem Details
Jeder Fehler von /v1 ist ein Problem nach RFC 9457 mit echtem HTTP-Status, einem Code zum Verzweigen und einer Request-Id für den Support.
API-Key anlegen und Scopes wählen
Ein API-Key für die REST-API, eigene Agenten und Dienste, mit genau den Scopes, die du ihm gibst.