AthausDoku

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

  1. Ein Mitglied des Büros öffnet 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 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_... 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.

Was bei /v1 nicht geht

ZugriffAntwort
Sitzungs-Cookie der Appwird nicht gelesen, also 401
Kein Kopf, ein falscher oder ein widerrufener Key401 mit dem Kopf WWW-Authenticate
Key einer Person ohne Büro401

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

StatusCodeUrsache
401unauthorizedder Key fehlt, ist ungültig oder widerrufen, oder seine Person hat kein Büro
403insufficient_permissionsdem Key fehlt der Scope oder die Stufe auf der Ressource
403plan_requiredder Tarif des Büros hat keinen API-Zugang
429rate_limitedzu viele Fehlversuche von einer Adresse

Weiter lesen

Auf dieser Seite