Skip to main content

​
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 anmelden und über 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:

​
Bearer-Token (Dashboard-Benutzer)

Verwenden Sie für Dashboard-Benutzer JWT Bearer-Tokens:
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.

​
API-Schlüsselformat

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.

​
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: 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:
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:
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.
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.