Skip to main content

​
Authentication

Orbit authenticates API requests two ways: an API key for server-to-server calls, and a session Bearer token for dashboard users. Enterprise organizations can additionally sign users in through SAML single sign-on and provision them through SCIM. Pick the method that matches how the request is made.

​
API Key (Server-to-Server)

Include your API key in the X-API-Key header:

​
Bearer Token (Dashboard Users)

For dashboard users, use JWT Bearer tokens:
You may also pass an API key via Authorization: Bearer dv_live_pk_... (any dv_ key — dv_live_sk_, dv_test_sk_, dv_live_pk_, dv_test_pk_) for environments where the X-API-Key custom header is blocked by CORS. The server accepts either form: it reads X-API-Key first, then falls back to a Bearer token that carries a dv_ prefix. A JWT (which starts with eyJ) is still treated as a dashboard session token, so the two never collide.

​
API Key Format

A public key (dv_live_pk_ / dv_test_pk_) is meant to be embedded in client-side code, so it is restricted to read-only scopes at creation. Write and administrative scopes — messages:write, contacts:write, admin, the * wildcard, and the sensitive account reads billing:read / settings:read — are rejected for a public key with a 422. Use a secret key (dv_live_sk_) for any operation that sends or modifies data.Still treat any key you ship to a browser or mobile bundle as publicly visible and scope it to the minimum reads it needs.

​
Single sign-on (SAML)

Enterprise organizations can log dashboard users in through a SAML 2.0 identity provider — Okta, Microsoft Entra ID (formerly Azure AD), OneLogin, Google Workspace, or PingFederate. SSO authenticates people into the dashboard; it does not mint API keys, so server-to-server calls still use the methods above. An owner configures the connection under Settings → Single sign-on in the dashboard (or via PATCH /api/v1/settings/saml): set your IdP’s SSO URL, entity ID, and signing certificate, then use Test connection before enabling it. Each organization gets its own set of endpoints, keyed by your organization slug (orgSlug). They live at the API root, not under /api/v1: Point your IdP at the metadata endpoint, for example https://api.orbit.devotel.io/auth/saml/acme/metadata for the acme organization.

​
Directory provisioning (SCIM)

Provision and deprovision dashboard users automatically from your identity provider over SCIM 2.0. Generate a provisioning token under Settings → SCIM (or via POST /api/v1/settings/scim/generate-token) — the token is shown once, so copy it into your IdP immediately. Your IdP sends the token as a Bearer credential on every request:
Endpoints follow the SCIM 2.0 spec and return application/scim+json. They are keyed by your organization slug and live at the API root, not under /api/v1:
SAML and SCIM are independent: SSO controls how users sign in, SCIM controls which users exist. You can enable either on its own, though most IdPs configure both together.