API v1

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.

  1. Adressen finden

    Jede 401-Antwort der API nennt im Header WWW-Authenticate die Adresse der Metadaten (resource_metadata, RFC 9728). Sie führen zum Autorisierungsserver, dessen Metadaten (RFC 8414) alle Endpunkte und die Scopes nennen.

    cURL
    curl https://www.briefsenden.com/.well-known/oauth-protected-resource/api/v1
    curl https://www.briefsenden.com/.well-known/oauth-authorization-server
  2. App registrieren

    Ihre App registriert sich einmal selbst (RFC 7591) und erhält eine client_id. redirect_uris nimmt 1 bis 10 Adressen: https, http nur auf dem eigenen Rechner (localhost) oder ein eigenes App-Schema wie myapp://callback. Den client_name sieht der Nutzer auf der Zustimmungsseite.

    cURL
    curl -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
    }
  3. Zustimmung einholen

    Erzeugen Sie code_verifier und code_challenge und ö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 mit code und state zu Ihrer redirect_uri zurück, bei Ablehnung mit error=access_denied. Ohne scope fragt die App alle Berechtigungen an.

    Browser
    https://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
  4. Code gegen Tokens tauschen

    Senden Sie den code zusammen mit dem code_verifier an den Token-Endpunkt. Die Antwort enthält das access_token, seine Laufzeit in Sekunden (expires_in) und immer ein refresh_token.

    cURL
    curl -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
  5. API aufrufen

    Senden Sie das Access-Token im Header Authorization an https://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.

    cURL
    curl https://www.briefsenden.com/api/v1/balance \
      -H "Authorization: Bearer ACCESS_TOKEN"
  6. 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 neues refresh_token, verwenden Sie ab dann dieses.

    cURL
    curl -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.

  1. Agent registrieren

    Der Agent registriert sich ohne Anmeldung und ohne redirect_uris. Die Antwort enthält client_id und client_secret; das Secret steht nur in dieser Antwort und gehört in jede weitere Anfrage des Agenten. Den client_name sieht der Nutzer später auf der Seite „Agent verbinden“; er darf den Namen briefsenden nicht enthalten. Registrierungen sind begrenzt: Bei 429 nennt Retry-After die Wartezeit.

    cURL
    curl -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
    }
  2. Vor der Verbindung: nur Kosten schätzen

    Mit grant_type=client_credentials erhält der Agent ein Token ohne Konto. Es gilt nur für POST /estimate und POST /serial/estimate; jeder andere Endpunkt antwortet mit 403. 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.

    cURL
    curl -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}'
  3. Code und Link anfordern

    Der Agent fordert einen Code an. scope ist Pflicht: Er nennt nur die Scopes, die er braucht. Er zeigt dem Nutzer verification_uri und user_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.

    cURL
    curl -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
    }
  4. Auf die Entscheidung warten

    Der Agent fragt den Token-Endpunkt im Abstand interval (5 Sekunden) mit dem device_code ab. Solange der Nutzer nicht entschieden hat, lautet die Antwort authorization_pending, bei zu schnellen Abfragen slow_down, nach einer Ablehnung access_denied. Nach der Verbindung enthält sie access_token und refresh_token für die freigegebenen Scopes; ab dann gelten die Schritte „API aufrufen“ und „Token erneuern“ von oben, jeweils mit client_secret. Ist der Code abgelaufen (expired_token), fordert der Agent einen neuen an.

    cURL
    curl -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").

ScopeErlaubtEndpunkte unter /api/v1
letters:readBriefe und Serienbriefe ansehenGET /letters, /letters/{id}, /serial, /serial/{id}, /serial/{id}/letters
letters:writeBriefe versenden und Serienbriefe abbrechenPOST /letters, /letters/structured, /letters/simple, /letters/bulk · DELETE /serial/{id}
balance:readGuthaben ansehen und Kosten schätzenGET /balance · POST /estimate, /serial/estimate
sender-profiles:readAbsenderprofile ansehenGET /sender-profiles
sender-profiles:writeAbsenderprofile anlegen, ändern und löschenPOST, PUT, DELETE /sender-profiles
addresses:readAdressbuch ansehenGET /addresses
addresses:writeAdressen anlegen, ändern und löschenPOST, PUT, DELETE /addresses
webhooks:readWebhooks ansehenGET /webhooks
webhooks:writeWebhooks anlegen und löschenPOST, DELETE /webhooks

OAuth-Endpunkte

Adressen des Autorisierungsservers

MethodeEndpointBeschreibung
GET/.well-known/oauth-protected-resource/api/v1Metadaten der API: Autorisierungsserver und Scopes (RFC 9728)
GET/.well-known/oauth-authorization-serverMetadaten des Autorisierungsservers: alle Endpunkte (RFC 8414)
POST/api/oauth/registerApp registrieren (RFC 7591)
GET/api/oauth/authorizeZustimmung des Nutzers im Browser
POST/api/oauth/agent/registerAgent ohne Browser registrieren (auth.md)
POST/api/oauth/deviceCode und Link für die Verbindung anfordern (RFC 8628)
GET/api/oauth/claimSeite „Agent verbinden“: Der Nutzer tippt den Code
POST/api/oauth/tokenCode, Device-Code oder Refresh-Token gegen Tokens tauschen
POST/api/oauth/revokeToken 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 .

Kostenloser Testmodus – keine Kreditkarte nötig

Jetzt integrieren

Erstellen Sie ein kostenloses Konto und testen Sie den OAuth-Ablauf im Testmodus, ohne dass ein Brief gedruckt wird.

Keine Grundgebühr Keine Mindestmenge Pay-per-Letter