​

Authentication

​

API Key (Server-to-Server)

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

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"))

​

Bearer Token (Dashboard Users)

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

​

API Key Format

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"}]}'

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)."
  }
}

​

Create your first key in the dashboard

1. Type — the same four classes as the format table: live secret (dv_live_sk_), test secret (dv_test_sk_), live public (dv_live_pk_), or test public (dv_test_pk_). Pick a test secret for a first integration: it can never deliver real traffic or bill your wallet, so your first run is free of side effects.
2. Scopes — grant the minimum the integration needs. Public keys accept read-only scopes only; write and administrative scopes are rejected at creation, as the example above shows.
3. Expiry — optionally give the key an expires_at. A key with no expiry stays valid until you rotate or revoke it; a short expiry suits trials and CI runners.

​

Manage the key after creation

• Grace (default). The old key stays valid for grace_period_hours (default 24, clamped to 1–168 hours) so both keys authenticate while you migrate. The response’s old_key_expires_at tells you the exact cutoff — it is the earlier of the old key’s original expires_at and the end of the grace window.
• Immediate. The old key is revoked in the same transaction. Reserve this for a leaked key; routine rotations should always overlap.

• Usage limits — a requests-per-minute rate limit and a monthly request quota per key (or as an org-wide default), so a noisy or compromised key trips its own 429 instead of consuming the throughput your other keys share.
• Usage budget alerts — a lightweight per-operator threshold on a key’s analytics drawer that badges the key as usage crosses 80% and 100% of the ceiling.
• Spend budgets — a persisted monthly money ceiling per key (minor currency units plus ISO-4217 currency) with one alert per threshold, shared with your whole team.

​

What to do when a key leaks

1. Revoke first. Send POST /api/v1/settings/api-keys/:id/revoke before anything else. Revoking a leaked key stops the meter at the revoke timestamp — usage billed into your account ends there regardless of what the leaked key does afterward — so revocation is always the right first move, even before you investigate.
2. Mint a replacement. If the integration must keep working, rotate with mode: "immediate" instead of a bare revoke: the replacement is minted and the old key is killed in one transaction. Copy the new plaintext from the rotation response — it is the only place it ever appears.
3. Review the damage path. Check the key’s usage in its analytics drawer (usage limits) and its audit log entries — grace rotations write api_key.rotated, panic-revokes write api_key.revoked_immediate, so a compliance review can tell them apart.
4. Prevent the repeat. Scope the replacement minimally, add an IP allowlist so the key only works from your network, and consider an expiry so forgetful cleanup stops being a risk.

​

Troubleshooting

​

Single sign-on (SAML)

<?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>

​

Directory provisioning (SCIM)

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

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
  }'

{
  "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"
  }
}