OAuth 2.0 für die Briefversand-API
Mit OAuth 2.0 greifen Apps und Agenten im Namen eines briefsenden-Kontos auf die API zu: Der Kontoinhaber meldet sich an und gibt den Zugriff selbst frei. Ihre App erhält ein Access-Token mit genau den erlaubten Berechtigungen, nie Passwort oder API-Key.
API-Key oder OAuth 2.0?
Beide Wege führen zu denselben Endpunkten unter /api/v1
API-Key
Für Ihre eigene Software und Ihr eigenes Konto. Sie erstellen den Key im Dashboard und senden ihn im Header X-Api-Key. Ein API-Key darf alle Endpunkte nutzen. Authentifizierung mit API-Key
OAuth 2.0
Für Apps und Agenten, die für andere briefsenden-Konten arbeiten. Jeder Nutzer stimmt im Browser zu, sieht die angefragten Berechtigungen und kann den Zugriff jederzeit widerrufen.
Ablauf: Authorization Code mit PKCE
Von der Registrierung bis zum ersten API-Aufruf
Die API unterstützt den Authorization Code Flow für öffentliche Clients: Es gibt kein Client-Secret, dafür ist PKCE Pflicht; verwenden Sie S256. Alle Adressen liegen unter https://www.briefsenden.com.
Adressen finden
Jede
401-Antwort der API nennt im HeaderWWW-Authenticatedie Adresse der Metadaten (resource_metadata, RFC 9728). Sie führen zum Autorisierungsserver, dessen Metadaten (RFC 8414) alle Endpunkte und die Scopes nennen.cURLcurl https://www.briefsenden.com/.well-known/oauth-protected-resource/api/v1 curl https://www.briefsenden.com/.well-known/oauth-authorization-server
App registrieren
Ihre App registriert sich einmal selbst (RFC 7591) und erhält eine
client_id.redirect_urisnimmt 1 bis 10 Adressen:https,httpnur auf dem eigenen Rechner (localhost) oder ein eigenes App-Schema wiemyapp://callback. Denclient_namesieht der Nutzer auf der Zustimmungsseite.cURLcurl -X POST https://www.briefsenden.com/api/oauth/register \ -H "Content-Type: application/json" \ -d '{"client_name": "Demo-App", "redirect_uris": ["https://app.example.com/callback"]}' # 201 Created { "client_id": "0f8fad5bd9cb469fa16570867728950e", "client_name": "Demo-App", "redirect_uris": ["https://app.example.com/callback"], "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"], "token_endpoint_auth_method": "none", "scope": "letters:read letters:write balance:read …", "client_id_issued_at": 1794441600 }Zustimmung einholen
Erzeugen Sie
code_verifierundcode_challengeund öffnen Sie diese Adresse im Browser des Nutzers. Er meldet sich bei briefsenden.com an, sieht App, Rücksprungziel und Berechtigungen und entscheidet. Danach kommt der Browser mitcodeundstatezu Ihrerredirect_urizurück, bei Ablehnung miterror=access_denied. Ohnescopefragt die App alle Berechtigungen an.Browserhttps://www.briefsenden.com/api/oauth/authorize ?response_type=code &client_id=0f8fad5bd9cb469fa16570867728950e &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback &scope=letters%3Awrite%20balance%3Aread &state=af0ifjsldkj &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM &code_challenge_method=S256 &resource=https%3A%2F%2Fwww.briefsenden.com%2Fapi%2Fv1
Code gegen Tokens tauschen
Senden Sie den
codezusammen mit demcode_verifieran den Token-Endpunkt. Die Antwort enthält dasaccess_token, seine Laufzeit in Sekunden (expires_in) und immer einrefresh_token.cURLcurl -X POST https://www.briefsenden.com/api/oauth/token \ -d grant_type=authorization_code \ -d client_id=0f8fad5bd9cb469fa16570867728950e \ -d redirect_uri=https://app.example.com/callback \ -d code=CODE \ -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk \ -d resource=https://www.briefsenden.com/api/v1
API aufrufen
Senden Sie das Access-Token im Header
Authorizationanhttps://www.briefsenden.com/api/v1. Endpunkte, Fehlerformat und Webhooks sind dieselben wie mit API-Key, siehe API-Dokumentation. Rate Limit und Idempotency-Keys zählen je Freigabe.cURLcurl https://www.briefsenden.com/api/v1/balance \ -H "Authorization: Bearer ACCESS_TOKEN"
Token erneuern
Ist das Access-Token abgelaufen, antwortet die API mit
401. Mit dem Refresh-Token holen Sie ein neues, ohne dass der Nutzer erneut zustimmt. Enthält die Antwort ein neuesrefresh_token, verwenden Sie ab dann dieses.cURLcurl -X POST https://www.briefsenden.com/api/oauth/token \ -d grant_type=refresh_token \ -d client_id=0f8fad5bd9cb469fa16570867728950e \ -d refresh_token=REFRESH_TOKEN \ -d resource=https://www.briefsenden.com/api/v1
Agenten ohne Browser: Registrierung und Claim
Der Agent registriert sich selbst, der Nutzer verbindet ihn per Code
Ein Agent ohne eigenen Browser und ohne Rücksprungadresse nutzt die Agent-Registrierung nach auth.md: Er registriert sich anonym, zeigt dem Nutzer einen Link und einen Code, und der Nutzer verbindet den Agenten auf briefsenden.com mit seinem Konto (Device-Flow, RFC 8628). Vor dieser Verbindung kann der Agent nur Kosten schätzen; er löst weder Druck noch Kosten aus. Die maschinenlesbare Fassung steht unter /auth.md.
Agent registrieren
Der Agent registriert sich ohne Anmeldung und ohne
redirect_uris. Die Antwort enthältclient_idundclient_secret; das Secret steht nur in dieser Antwort und gehört in jede weitere Anfrage des Agenten. Denclient_namesieht der Nutzer später auf der Seite „Agent verbinden“; er darf den Namen briefsenden nicht enthalten. Registrierungen sind begrenzt: Bei429nenntRetry-Afterdie Wartezeit.cURLcurl -X POST https://www.briefsenden.com/api/oauth/agent/register \ -H "Content-Type: application/json" \ -d '{"client_name": "Demo-Agent"}' # 201 Created { "client_id": "0f8fad5bd9cb469fa16570867728950e", "client_secret": "CLIENT_SECRET", "client_name": "Demo-Agent", "grant_types": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token", "client_credentials"], "token_endpoint_auth_method": "client_secret_post", "scope": "letters:read letters:write balance:read …", "client_id_issued_at": 1794441600, "client_secret_expires_at": 0 }Vor der Verbindung: nur Kosten schätzen
Mit
grant_type=client_credentialserhält der Agent ein Token ohne Konto. Es gilt nur fürPOST /estimateundPOST /serial/estimate; jeder andere Endpunkt antwortet mit403. Verwenden Sie das Token bis zu seinem Ablauf (expires_in) weiter: Je Agent sind 10 Token-Anfragen in 10 Minuten möglich. Dieser Schritt ist optional.cURLcurl -X POST https://www.briefsenden.com/api/oauth/token \ -d grant_type=client_credentials \ -d client_id=0f8fad5bd9cb469fa16570867728950e \ -d client_secret=CLIENT_SECRET curl -X POST https://www.briefsenden.com/api/v1/estimate \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"pages": 2}'Code und Link anfordern
Der Agent fordert einen Code an.
scopeist Pflicht: Er nennt nur die Scopes, die er braucht. Er zeigt dem Nutzerverification_uriunduser_code. Der Nutzer öffnet den Link, meldet sich an, tippt den Code selbst ein, sieht den Namen des Agenten und die Berechtigungen und verbindet oder lehnt ab. Nach dem Verbinden erhält der Kontoinhaber eine E-Mail mit dem Namen des Agenten und dem Weg zum Widerruf. Der Code gilt 10 Minuten (expires_in); je Agent sind 5 Codes in 10 Minuten möglich.cURLcurl -X POST https://www.briefsenden.com/api/oauth/device \ -d client_id=0f8fad5bd9cb469fa16570867728950e \ -d client_secret=CLIENT_SECRET \ -d "scope=letters:write balance:read" # 200 OK { "device_code": "DEVICE_CODE", "user_code": "1234-5678-9012", "verification_uri": "https://www.briefsenden.com/api/oauth/claim", "interval": 5, "expires_in": 600 }Auf die Entscheidung warten
Der Agent fragt den Token-Endpunkt im Abstand
interval(5 Sekunden) mit demdevice_codeab. Solange der Nutzer nicht entschieden hat, lautet die Antwortauthorization_pending, bei zu schnellen Abfragenslow_down, nach einer Ablehnungaccess_denied. Nach der Verbindung enthält sieaccess_tokenundrefresh_tokenfür die freigegebenen Scopes; ab dann gelten die Schritte „API aufrufen“ und „Token erneuern“ von oben, jeweils mitclient_secret. Ist der Code abgelaufen (expired_token), fordert der Agent einen neuen an.cURLcurl -X POST https://www.briefsenden.com/api/oauth/token \ -d grant_type=urn:ietf:params:oauth:grant-type:device_code \ -d device_code=DEVICE_CODE \ -d client_id=0f8fad5bd9cb469fa16570867728950e \ -d client_secret=CLIENT_SECRET # 400 Bad Request { "error": "authorization_pending" } # 200 OK { "access_token": "…", "token_type": "Bearer", "expires_in": …, "refresh_token": "…" }
Scopes
Berechtigungen, die der Nutzer freigibt
Ein Scope auf :read gilt für GET, ein Scope auf :write für alle anderen Methoden. balance:read deckt auch die Kostenschätzung. Fehlt dem Token der Scope eines Endpunkts, antwortet die API mit 403 und nennt ihn im Header WWW-Authenticate (error="insufficient_scope").
| Scope | Erlaubt | Endpunkte unter /api/v1 |
|---|---|---|
| letters:read | Briefe und Serienbriefe ansehen | GET /letters, /letters/{id}, /serial, /serial/{id}, /serial/{id}/letters |
| letters:write | Briefe versenden und Serienbriefe abbrechen | POST /letters, /letters/structured, /letters/simple, /letters/bulk · DELETE /serial/{id} |
| balance:read | Guthaben ansehen und Kosten schätzen | GET /balance · POST /estimate, /serial/estimate |
| sender-profiles:read | Absenderprofile ansehen | GET /sender-profiles |
| sender-profiles:write | Absenderprofile anlegen, ändern und löschen | POST, PUT, DELETE /sender-profiles |
| addresses:read | Adressbuch ansehen | GET /addresses |
| addresses:write | Adressen anlegen, ändern und löschen | POST, PUT, DELETE /addresses |
| webhooks:read | Webhooks ansehen | GET /webhooks |
| webhooks:write | Webhooks anlegen und löschen | POST, DELETE /webhooks |
OAuth-Endpunkte
Adressen des Autorisierungsservers
| Methode | Endpoint | Beschreibung |
|---|---|---|
| GET | /.well-known/oauth-protected-resource/api/v1 | Metadaten der API: Autorisierungsserver und Scopes (RFC 9728) |
| GET | /.well-known/oauth-authorization-server | Metadaten des Autorisierungsservers: alle Endpunkte (RFC 8414) |
| POST | /api/oauth/register | App registrieren (RFC 7591) |
| GET | /api/oauth/authorize | Zustimmung des Nutzers im Browser |
| POST | /api/oauth/agent/register | Agent ohne Browser registrieren (auth.md) |
| POST | /api/oauth/device | Code und Link für die Verbindung anfordern (RFC 8628) |
| GET | /api/oauth/claim | Seite „Agent verbinden“: Der Nutzer tippt den Code |
| POST | /api/oauth/token | Code, Device-Code oder Refresh-Token gegen Tokens tauschen |
| POST | /api/oauth/revoke | Token widerrufen (RFC 7009) |
Testmodus und Kosten
OAuth-Tokens haben keinen eigenen Test- und Live-Schalter wie die API-Keys (bv_test_…, bv_live_…). Briefe folgen dem Testmodus des Kontos: Im Testmodus werden sie nicht gedruckt und kosten keine Coins, sonst werden sie gedruckt, versendet und mit Coins bezahlt. Darf die App Briefe versenden, zeigt die Zustimmungsseite dem Nutzer vorher, was gilt.
Zugriff widerrufen
Der Nutzer widerruft den Zugriff jederzeit unter Einstellungen → Entwickler → Verbundene Apps. Access- und Refresh-Token gelten dann ab der nächsten Anfrage nicht mehr. Je App und Konto gibt es eine Freigabe: Stimmt der Nutzer derselben App erneut zu, ersetzt die neue Freigabe die alte samt ihrer Tokens. Agenten, die nie mit einem Konto verbunden wurden, werden frühestens einen Tag nach der Registrierung gelöscht, Apps ohne jede Zustimmung frühestens nach 7 Tagen; sie registrieren sich bei Bedarf neu. Einmal verbundene Apps und Agenten bleiben registriert, auch nach einem Widerruf.
Endpunkte, Webhooks, Fehlerformat und Swagger-UI: zur API-Dokumentation .
Jetzt integrieren
Erstellen Sie ein kostenloses Konto und testen Sie den OAuth-Ablauf im Testmodus, ohne dass ein Brief gedruckt wird.