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:

curl https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_live_sk_your_key_here"

The same call through an official SDK keeps the key in one place — the client you init once on your backend:

Node.js
Python
Go

import { Orbit } from '@devotel-orbit/node';

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))

Set ORBIT_API_KEY on your server, never in client-side code. Full install and usage for every language is under SDKs.

Bearer Token (Dashboard Users)

For dashboard users, use JWT Bearer tokens:

curl https://api.orbit.devotel.io/api/v1/messages \
  -H "Authorization: Bearer eyJhbG..."

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

Type	Prefix	Usage
Live Secret	`dv_live_sk_`	Server-side API calls
Test Secret	`dv_test_sk_`	Server-side API calls (test mode)
Live Public	`dv_live_pk_`	Client-side (browser SDKs)
Test Public	`dv_test_pk_`	Client-side (test mode)

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.A scoped public key works — this one carries only messages:read:

curl https://api.orbit.devotel.io/sdk/track \
  -X POST \
  -H "X-API-Key: dv_live_pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"anonymous_id": "anon_8f3c2b1d", "events": [{"name": "page_viewed"}]}'

Ask to mint that same key with a write scope and the create call is rejected:

curl -X POST https://api.orbit.devotel.io/api/v1/settings/api-keys \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "browser-sdk", "type": "public", "scopes": ["messages:read", "messages:write"]}'

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Public keys cannot hold write or administrative scopes (messages:write)."
  }
}

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:

Method	Endpoint	Purpose
GET	`/auth/saml/{orgSlug}/metadata`	Service-provider metadata XML to import into your IdP
GET	`/auth/saml/{orgSlug}/login`	Start the SSO flow (redirects to your IdP)
POST	`/auth/saml/{orgSlug}/callback`	Assertion Consumer Service (ACS) — your IdP posts the signed response here
GET	`/auth/saml/{orgSlug}/logout`	Start single logout

Point your IdP at the metadata endpoint, for example https://api.orbit.devotel.io/auth/saml/acme/metadata for the acme organization. The response — served as application/xml — is the service-provider descriptor your IdP admin imports:

<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://api.orbit.devotel.io/auth/saml/acme/metadata"><md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"><md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://api.orbit.devotel.io/auth/saml/acme/logout"/><md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat><md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://api.orbit.devotel.io/auth/saml/acme/callback" index="0" isDefault="true"/></md:SPSSODescriptor></md:EntityDescriptor>

The metadata is public and safe to paste into your IdP directly — it carries our ACS and logout URLs and the email NameIDFormat, no secrets.

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:

curl https://api.orbit.devotel.io/scim/v2/acme/Users \
  -H "Authorization: Bearer <your-scim-token>"

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:

Resource	Endpoints
Users	`/scim/v2/{orgSlug}/Users` (list, create), `/scim/v2/{orgSlug}/Users/{id}` (get, replace, patch, delete)
Groups	`/scim/v2/{orgSlug}/Groups` (list, create/update), `/scim/v2/{orgSlug}/Groups/{id}` (get)
Discovery	`/scim/v2/{orgSlug}/ServiceProviderConfig`, `/ResourceTypes`, `/Schemas`

A worked user create — the exact shape your IdP (or a direct client) sends and gets back for POST /scim/v2/{orgSlug}/Users:

curl -X POST https://api.orbit.devotel.io/scim/v2/acme/Users \
  -H "Authorization: Bearer <your-scim-token>" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "ada@acme.example",
    "name": { "givenName": "Ada", "familyName": "Lovelace" },
    "displayName": "Ada Lovelace",
    "emails": [{ "value": "ada@acme.example", "primary": true }],
    "active": true
  }'

The 201 response is the created User resource, application/scim+json:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "usr_01HTWQ3X2",
  "userName": "ada@acme.example",
  "name": { "givenName": "Ada", "familyName": "Lovelace" },
  "displayName": "Ada Lovelace",
  "emails": [{ "value": "ada@acme.example", "primary": true }],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2026-09-06T12:04:31.512Z",
    "location": "https://api.orbit.devotel.io/scim/v2/acme/Users/usr_01HTWQ3X2"
  }
}

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.

For the full provisioning walkthrough — base URL construction, role mapping, IdP health checks, and Okta / Entra / generic-client steps — see the SCIM 2.0 provisioning guide.

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Authenticate Orbit API requests with keys and tokens

Authentication

API Key (Server-to-Server)

Bearer Token (Dashboard Users)

API Key Format

Single sign-on (SAML)

Directory provisioning (SCIM)

​Authentication

​API Key (Server-to-Server)

​Bearer Token (Dashboard Users)

​API Key Format

​Single sign-on (SAML)

​Directory provisioning (SCIM)

Authentication

API Key (Server-to-Server)

Bearer Token (Dashboard Users)

API Key Format

Single sign-on (SAML)

Directory provisioning (SCIM)