> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fynn.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentifizierung

> API-Token für die Einrichtung und Kunden-Token für den Tarifwechsel im Kundenbereich.

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.

<Steps>
  <Step title="Token erstellen">
    Lege ein API-Token in den Entwickler-Einstellungen an. Eine ausführliche Anleitung findest du unter [Authentication](/api-reference/authentication).
  </Step>

  <Step title="Token senden">
    Schicke das Token bei jeder Anfrage im Authorization-Header mit.
  </Step>
</Steps>

```bash theme={null}
curl https://coreapi.io/api/plans \
  -H "Authorization: Bearer api_DEIN_TOKEN"
```

Referenz: [Plans listen](/v2-plans-api/plans/list-plans).

<Warning>
  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.
</Warning>

## 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`):

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://coreapi.io/customers/CUSTOMER_ID/authenticate \
    -H "Authorization: Bearer api_DEIN_TOKEN"
  ```

  ```json Response theme={null}
  {
    "data": {
      "accessToken": "...",
      "refreshToken": "...",
      "customerAreaLink": "https://..."
    }
  }
  ```
</CodeGroup>

Den `accessToken` schickst du dann als Bearer-Token an die Kundenbereich-Endpunkte:

```bash theme={null}
curl https://coreapi.io/api/customer/subscriptions/SUBSCRIPTION_ID/plan-options \
  -H "Authorization: Bearer CUSTOMER_TOKEN"
```

Referenz: [Tarifoptionen abrufen](/v2-plans-api/customer/plan-options).

Alternativ stammt das Token aus einer Kundenbereich-Sitzung (Portal). Wie du Kunden anmeldest und welche Flows es gibt, beschreiben der [OAuth2-Flow](/guide/oauth2/introduction) und der Abschnitt zur Kunden-Authentifizierung unter [Authentication](/api-reference/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:

```bash theme={null}
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.

<Note>
  Ein Tarifwechsel ist bewusst nur im Kundenbereich möglich, nicht in der Wallet. So entscheidet immer der Kunde selbst über seinen Auf- oder Abstieg.
</Note>

## 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).