Authentifizierung

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

Umgebung	Basis-URL
Produktion	`https://coreapi.io`
Sandbox	`https://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.

Token erstellen

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

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"

{
  "data": {
    "accessToken": "...",
    "refreshToken": "...",
    "customerAreaLink": "https://..."
  }
}

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

Berechtigung	Wofür
`plan:read`	Pläne und Checkout-Links lesen
`plan:write`	Pläne anlegen, ändern, aktivieren, löschen und Checkout-Links erstellen
`customer:plan:switch`	Tarifoptionen abrufen, Wechsel-Vorschau und Wechsel (mit Kunden-Token)
`customer:authenticate`	Kunden-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).

Einführung

Grundlagen

Pläne

Angebote

Provisionen

Zahlungspläne

Basis-URLs

Einrichtung: API-Token

Kundenbereich: Kunden-Token

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

Berechtigungen

​Basis-URLs

​Einrichtung: API-Token

​Kundenbereich: Kunden-Token

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

​Berechtigungen

Basis-URLs

Einrichtung: API-Token

Kundenbereich: Kunden-Token

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

Berechtigungen