Nyilvános API

OAuth-alkalmazások

Ha nem a saját fiókodat kezeled, hanem másokét: authorization code folyamat kötelező PKCE-vel és lejáró tokenekkel.

Brauchst du das?

Was du baustWas du nutzen sollst
Ein Skript oder eine Automatisierung für deinen eigenen Arbeitsbereich.API-Schlüssel. Siehe die Seite Authentifizierung.
Ein KI-Agent für deinen eigenen Kalender.MCP-Schlüssel. Siehe den Abschnitt MCP.
Eine App, die andere mit ihrem eigenen Posty-Konto nutzen.OAuth. Diese Seite.
Die meisten Leser brauchen das nicht

Wenn du Code für dein eigenes Konto schreibst, ist der API-Schlüssel einfacher und kann genau so viel. OAuth brauchst du, wenn deine Nutzer mit ihrem eigenen Posty-Konto deiner App Zugriff geben.

Der Ablauf

  1. 1
    Registrier die App
    Ein Superadmin des Arbeitsbereichs kann eine App zulassen. Bei der Registrierung gibst du die Redirect-URIs an.
  2. 2
    Schick den Nutzer auf die Autorisierungsseite
    Authorization-Code-Ablauf, PKCE ist Pflicht. Hier sieht der Nutzer, welche Berechtigung du anfragst.
  3. 3
    Tausch den Code gegen ein Token
    Du schickst den erhaltenen Code und den PKCE-Verifier und bekommst ein Zugriffstoken.
  4. 4
    Ruf die API mit dem Token auf
    Das Token geht mit dem Präfix Bearer in den Authorization-Header.
curl https://api.posty.hu/public/v1/integrations \
  -H "Authorization: Bearer pos_a_tokened"

Was Pflicht ist

  • PKCE mit S256-Challenge, bei jeder Anfrage. Auch ein Client ohne Secret kann registriert werden, ohne PKCE nicht.
  • Die redirect_uri muss exakt übereinstimmen mit der registrierten Liste. Kein Präfixabgleich, kein Platzhalter.
  • Tokens laufen ab, und den Refresh-Token rotieren wir. Wir speichern nur die gehashte Form.
  • Ein Superadmin lässt die App zu im Arbeitsbereich.

Tokens

Das Token gilt für die Scopes, denen der Nutzer zugestimmt hat. Bei jedem Aufruf schneiden wir sie mit der aktuellen Rolle des Nutzers. Eine Herabstufung gilt beim nächsten Aufruf. Du musst nicht warten, bis das Token abläuft.

Die Liste der Scopes ist dieselbe wie bei den API-Schlüsseln. Siehe die Seite Authentifizierung. Ein Token für die MCP-Ressource kann auf der REST-API nicht verwendet werden, und umgekehrt: Die beiden Ressourcen haben getrennte Kennungen, und wir prüfen die hinterlegte Audience.

Metadaten

Jede Adresse im Ablauf ist maschinenlesbar, dein Client muss sie also nicht fest einbauen:

DokumentAdresse
Authorization server metadatahttps://api.posty.hu/.well-known/oauth-authorization-server
Protected resource metadatahttps://api.posty.hu/.well-known/oauth-protected-resource
Metadaten der MCP-Ressourcehttps://api.posty.hu/.well-known/oauth-protected-resource/mcp-oauth

Die Antwort von /public/v1/status listet sie ebenfalls auf, ohne Authentifizierung.

Widerruf

Der Nutzer kann in Posty, auf der Seite Einstellungen → Autorisierte Apps, den Zugriff deiner App jederzeit widerrufen. Der Widerruf gilt sofort: Beim nächsten Aufruf bekommt das Token einen 401.

Fang das ab: Ein 401 ist kein Fehler, sondern die Entscheidung des Nutzers. Hol dir die Freigabe neu. Versuch es nicht noch einmal mit demselben Token.

Fehlt etwas auf dieser Seite? Schreib eine E-Mail an [email protected] oder nutze auf der Hilfeseite das Formular.