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

# Orbit API-Anfragen mit Schlüsseln und Tokens authentifizieren

> Authentifizieren Sie Orbit API-Anfragen mit API-Schlüsseln für Server-zu-Server-Aufrufe oder Bearer-Sitzungstokens sowie SAML SSO für Enterprise-Dashboard-Benutzer.

# Authentifizierung

Orbit authentifiziert **API-Anfragen** auf zwei Arten: ein API-Schlüssel für
Server-zu-Server-Aufrufe und ein Bearer-Sitzungstoken für Dashboard-Benutzer.
Enterprise-Organisationen können Benutzer zusätzlich über
[SAML Single Sign-On](#single-sign-on-saml) anmelden und über
[SCIM](#directory-provisioning-scim) bereitstellen. Wählen Sie die Methode,
die zur Art der Anfrage passt.

## API-Schlüssel (Server-zu-Server)

Fügen Sie Ihren API-Schlüssel im Header `X-API-Key` hinzu:

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

## Bearer-Token (Dashboard-Benutzer)

Verwenden Sie für Dashboard-Benutzer JWT Bearer-Tokens:

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/messages \
  -H "Authorization: Bearer eyJhbG..."
```

<Note>
  Sie können auch einen API-Schlüssel über `Authorization: Bearer dv_live_pk_...`
  übergeben (jeder `dv_`-Schlüssel — `dv_live_sk_`, `dv_test_sk_`, `dv_live_pk_`,
  `dv_test_pk_`), für Umgebungen, in denen der benutzerdefinierte Header
  `X-API-Key` durch CORS blockiert wird. Der Server akzeptiert beide Formen: Er
  liest zuerst `X-API-Key` und greift dann auf ein `Bearer`-Token mit `dv_`-Präfix
  zurück. Ein JWT (beginnt mit `eyJ`) wird weiterhin als Dashboard-Sitzungstoken
  behandelt, sodass die beiden niemals in Konflikt geraten.
</Note>

## API-Schlüsselformat

| Typ         | Präfix        | Verwendung                            |
| ----------- | ------------- | ------------------------------------- |
| Live Secret | `dv_live_sk_` | Serverseitige API-Aufrufe             |
| Test Secret | `dv_test_sk_` | Serverseitige API-Aufrufe (Testmodus) |
| Live Public | `dv_live_pk_` | Clientseitig (Browser-SDKs)           |
| Test Public | `dv_test_pk_` | Clientseitig (Testmodus)              |

<Warning>
  Ein öffentlicher Schlüssel (`dv_live_pk_` / `dv_test_pk_`) ist zur Einbettung
  in clientseitigen Code bestimmt und daher bei der Erstellung **auf schreibgeschützte
  Scopes beschränkt**. Schreib- und Verwaltungs-Scopes — `messages:write`,
  `contacts:write`, `admin`, der `*`-Wildcard sowie die sensiblen Konto-Lesevorgänge
  `billing:read` / `settings:read` — werden für einen öffentlichen Schlüssel mit
  einem `422`-Fehler abgelehnt. Verwenden Sie einen **Secret-Schlüssel**
  (`dv_live_sk_`) für alle Operationen, die Daten senden oder ändern.

  Behandeln Sie dennoch jeden Schlüssel, den Sie in ein Browser- oder Mobile-Bundle
  einfügen, als öffentlich sichtbar und beschränken Sie ihn auf die minimal
  erforderlichen Lesevorgänge.
</Warning>

## Single Sign-On (SAML)

Enterprise-Organisationen können Dashboard-Benutzer über einen SAML 2.0-Identitätsanbieter
anmelden — Okta, Microsoft Entra ID (ehemals Azure AD), OneLogin, Google Workspace
oder PingFederate. SSO authentifiziert Personen am Dashboard; es erstellt keine
API-Schlüssel, sodass Server-zu-Server-Aufrufe weiterhin die oben genannten
Methoden verwenden.

Ein Besitzer konfiguriert die Verbindung unter **Einstellungen → Single Sign-On**
im Dashboard (oder über `PATCH /api/v1/settings/saml`): Legen Sie die SSO-URL,
Entitäts-ID und das Signaturzertifikat Ihres IdP fest und verwenden Sie dann
**Verbindung testen**, bevor Sie es aktivieren.

Jede Organisation erhält ihren eigenen Satz von Endpunkten, die über Ihren
Organisations-Slug (`orgSlug`) adressiert werden. Sie befinden sich im API-Stamm,
**nicht** unter `/api/v1`:

| Methode | Endpunkt                        | Zweck                                                                        |
| ------- | ------------------------------- | ---------------------------------------------------------------------------- |
| GET     | `/auth/saml/{orgSlug}/metadata` | Service-Provider-Metadaten-XML zum Importieren in Ihren IdP                  |
| GET     | `/auth/saml/{orgSlug}/login`    | Startet den SSO-Fluss (leitet zu Ihrem IdP weiter)                           |
| POST    | `/auth/saml/{orgSlug}/callback` | Assertion Consumer Service (ACS) — Ihr IdP postet die signierte Antwort hier |
| GET     | `/auth/saml/{orgSlug}/logout`   | Startet Single Logout                                                        |

Richten Sie Ihren IdP auf den Metadaten-Endpunkt, zum Beispiel
`https://api.orbit.devotel.io/auth/saml/acme/metadata` für die Organisation
`acme`.

## Verzeichnisbereitstellung (SCIM)

Stellen Sie Dashboard-Benutzer automatisch über SCIM 2.0 von Ihrem Identitätsanbieter
bereit und entziehen Sie sie. Generieren Sie ein Bereitstellungstoken unter
**Einstellungen → SCIM** (oder über `POST /api/v1/settings/scim/generate-token`) —
das Token wird nur einmal angezeigt, kopieren Sie es daher sofort in Ihren IdP.

Ihr IdP sendet das Token bei jeder Anfrage als Bearer-Anmeldedaten:

```bash theme={null}
curl https://api.orbit.devotel.io/scim/v2/acme/Users \
  -H "Authorization: Bearer <your-scim-token>"
```

Endpunkte folgen der SCIM 2.0-Spezifikation und geben `application/scim+json`
zurück. Sie werden über Ihren Organisations-Slug adressiert und befinden sich
im API-Stamm, **nicht** unter `/api/v1`:

| Ressource | Endpunkte                                                                                                                |
| --------- | ------------------------------------------------------------------------------------------------------------------------ |
| Benutzer  | `/scim/v2/{orgSlug}/Users` (Auflisten, Erstellen), `/scim/v2/{orgSlug}/Users/{id}` (Abrufen, Ersetzen, Patchen, Löschen) |
| Gruppen   | `/scim/v2/{orgSlug}/Groups` (Auflisten, Erstellen/Aktualisieren), `/scim/v2/{orgSlug}/Groups/{id}` (Abrufen)             |
| Discovery | `/scim/v2/{orgSlug}/ServiceProviderConfig`, `/ResourceTypes`, `/Schemas`                                                 |

<Note>
  SAML und SCIM sind unabhängig: SSO steuert, wie sich Benutzer anmelden, SCIM
  steuert, welche Benutzer vorhanden sind. Sie können beide einzeln aktivieren,
  obwohl die meisten IdPs beide zusammen konfigurieren.
</Note>

Für die vollständige Bereitstellungsanleitung — Basis-URL-Konstruktion,
Rollenzuordnung, IdP-Integritätsprüfungen und Okta / Entra / generische
Client-Schritte — siehe
[SCIM 2.0-Bereitstellungsanleitung](/compliance/scim-provisioning).