Zum Hauptinhalt springen
Die Plan-API kennt zwei Kontexte. Die Einrichtung (Pläne anlegen, Checkout-Links erstellen) läuft serverseitig mit einem API-Token deiner Organisation. Der Tarifwechsel im Kundenbereich läuft im Namen eines Kunden mit einem Kunden-Token.

​
Basis-URLs

UmgebungBasis-URL
Produktionhttps://coreapi.io
Sandboxhttps://preview.coreapi.io
Alle Pfade in dieser Dokumentation beginnen mit /api, zum Beispiel https://coreapi.io/api/plans.

​
Einrichtung: API-Token

Setup-Endpunkte (alles unter /api/plans) authentifizierst du mit einem API-Token deiner Organisation. Das Token ist fest an genau eine Organisation gebunden, du brauchst also keinen zusätzlichen Organisations-Header.
1

Token erstellen

Lege ein API-Token in den Entwickler-Einstellungen an. Eine ausführliche Anleitung findest du unter Authentication.
2

Token senden

Schicke das Token bei jeder Anfrage im Authorization-Header mit.
curl https://coreapi.io/api/plans \
  -H "Authorization: Bearer api_DEIN_TOKEN"
Referenz: Plans listen.
Behandle API-Token wie ein Passwort. Sie haben vollen Zugriff im Rahmen ihrer Berechtigungen. Gib sie niemals im Browser oder in einer mobilen App preis.

​
Kundenbereich: Kunden-Token

Die drei Wechsel-Endpunkte unter /api/customer/... laufen im Kontext eines angemeldeten Kunden. Sie erwarten ein Kunden-Token (Bearer) mit der Berechtigung customer:plan:switch. Serverseitig erzeugst du ein solches Token mit deinem API-Token (Berechtigung customer:authenticate): 
curl -X POST https://coreapi.io/customers/CUSTOMER_ID/authenticate \
  -H "Authorization: Bearer api_DEIN_TOKEN"
Den accessToken schickst du dann als Bearer-Token an die Kundenbereich-Endpunkte: 
curl https://coreapi.io/api/customer/subscriptions/SUBSCRIPTION_ID/plan-options \
  -H "Authorization: Bearer CUSTOMER_TOKEN"
Referenz: Tarifoptionen abrufen. Alternativ stammt das Token aus einer Kundenbereich-Sitzung (Portal). Wie du Kunden anmeldest und welche Flows es gibt, beschreiben der OAuth2-Flow und der Abschnitt zur Kunden-Authentifizierung unter Authentication.

​
Im Namen eines Kunden handeln (X-On-Behalf-Of)

Für Server-zu-Server-Integrationen musst du nicht für jeden Kunden ein eigenes Token erzeugen. Du verwendest deinen API-Token und legst über den Header X-On-Behalf-Of fest, in wessen Namen die Anfrage läuft: 
curl https://coreapi.io/api/customer/subscriptions/SUBSCRIPTION_ID/plan-options \
  -H "Authorization: Bearer api_DEIN_TOKEN" \
  -H "X-On-Behalf-Of: customer:CUSTOMER_ID"
Die Anfrage läuft dann vollständig als dieser Kunde, mit dessen Berechtigungen wie customer:plan:switch. Voraussetzungen:
  • Dein API-Token braucht die Berechtigung customer:authenticate.
  • Der Kunde muss zu deiner Organisation gehören, sonst antwortet die API mit 404.
  • Während der Impersonation gelten ausschließlich die Kunden-Berechtigungen, nicht die Admin-Rechte deines Tokens. Reine Admin-Endpunkte sind in einer solchen Anfrage also nicht erreichbar.
So sparst du dir den separaten Token-Abruf und nutzt einen einzigen API-Token für alle Kundenbereich-Aktionen.
Ein Tarifwechsel ist bewusst nur im Kundenbereich möglich, nicht in der Wallet. So entscheidet immer der Kunde selbst über seinen Auf- oder Abstieg.

​
Berechtigungen

BerechtigungWofür
plan:readPläne und Checkout-Links lesen
plan:writePläne anlegen, ändern, aktivieren, löschen und Checkout-Links erstellen
customer:plan:switchTarifoptionen abrufen, Wechsel-Vorschau und Wechsel (mit Kunden-Token)
customer:authenticateKunden-Token erzeugen über POST /customers/{id}/authenticate (Admin)
Fehlt die nötige Berechtigung, antwortet die API mit 401 (nicht authentifiziert) oder 403 (authentifiziert, aber nicht berechtigt).