Auth API

Auth endpoints exposed by the Devotel CPaaS API Base path: /api/v1/auth Endpoint count: 7

The SAML SSO round-trip

These four operations are the service-provider side of SAML 2.0 SSO — the route an organization’s IdP administrators walk to wire Okta, Entra ID, or similar into Orbit’s sign-in. The page’s {orgSlug} path segment selects the SAML configuration; it is a URL-safe organization slug, not an API-key credential, and the operations are deliberately unauthenticated because they begin a session rather than require one. Sequence the round-trip like this. (1) GET /auth/saml/{orgSlug}/metadata returns the service-provider XML the IdP admin imports to register Orbit: entity ID, ACS URL, and signing details. (2) GET /auth/saml/{orgSlug}/login?redirect=/settings/team issues the SP-initiated AuthnRequest and 302-redirects the browser to the IdP’s SSO URL; any redirect value is signed into RelayState and sweeps the post-auth destination back. (3) The IdP POSTs the signed SAMLResponse to /auth/saml/{orgSlug}/callback — the Assertion Consumer Service verifies signature, audience, and the replay window, provisions the user on first login, then 302-redirects to the dashboard sign-in ticket that mints the session cookie. (4) GET /auth/saml/{orgSlug}/logout?nameId=<subject> builds a LogoutRequest for the IdP’s SLO endpoint when single logout is configured; otherwise it answers 200 with a logged_out status, and the local ceremony destroys the session. A worked check-in sequence in cURL:

cURL

# 1. Hand this metadata to the IdP admin
curl "https://api.orbit.devotel.io/auth/saml/acme-inc/metadata"

# 2. Start SSO — the browser redirects to the IdP
curl -I "https://api.orbit.devotel.io/auth/saml/acme-inc/login?redirect=/settings/team"

# 3. The IdP POSTs here on its own — no API key involved
#    POST /auth/saml/acme-inc/callback

# 4. Log out (with the subject's NameID when available)
curl -I "https://api.orbit.devotel.io/auth/saml/acme-inc/logout?nameId=user@acme.example"

The first event and the first callback are both redirect-only flows — do not call them from your application; point users at them or let the IdP drive the callback.

GET /api/v1/auth/impersonate-cookie-consume

Second half of the impersonation handoff. Reads the token from the cookie staged by the previous call, enforces one-time use, confirms the impersonation session has not been ended, clears the cookie and redirects the browser into the impersonated dashboard. The operator’s browser opens this URL directly, so the success path is a redirect rather than a JSON body, and a second visit to the same link is rejected.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/auth/impersonate-cookie-consume" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/auth/impersonate-cookie-consume', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/auth/impersonate-cookie-consume", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/auth/impersonate-cookie-consume", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/auth/impersonate-cookie-consume')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/auth/impersonate-cookie-consume');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {},
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Revoke every API key after a password reset

GET /api/v1/auth/post-reset-revoke-api-keys

Backs the Revoke all my API keys link in the email sent after a password reset. Validates the single-use token from the link, deactivates every API key the user created, drops them from the authentication cache so running services stop accepting them straight away, and burns the token. The link is valid for 24 hours and works once.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/auth/post-reset-revoke-api-keys" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/auth/post-reset-revoke-api-keys', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/auth/post-reset-revoke-api-keys", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/auth/post-reset-revoke-api-keys", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/auth/post-reset-revoke-api-keys')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/auth/post-reset-revoke-api-keys');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {},
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

POST /api/v1/auth/consent

Stores the signed-in user’s acceptance of the Terms of Service and Privacy Policy: the document versions they were shown, the moment they accepted, and the locale, IP address and user agent captured at that moment. Call it once from the signup or invite-acceptance flow as soon as the session exists. Posting again for the same user updates the existing record in place, so re-acceptance after a policy update is safe.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/auth/consent" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/auth/consent', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/auth/consent", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/auth/consent", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/auth/consent')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/auth/consent');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{}

{}

Request a password-reset email

POST /api/v1/auth/forgot-password

Starts a self-service password reset. When the address belongs to an account, Orbit emails a single-use reset link that expires after one hour; when it does not, no email is sent. The response is 200 either way, so the endpoint cannot be used to discover which addresses are registered. Requests are rate limited per IP address and per email address.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/auth/forgot-password" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/auth/forgot-password', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/auth/forgot-password", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/auth/forgot-password", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/auth/forgot-password')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/auth/forgot-password');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{}

POST /api/v1/auth/impersonate-cookie-set

First half of the impersonation handoff. Verifies the token and stores it in a five-minute, httpOnly, Secure, SameSite=Strict cookie so the operator’s browser can carry it to the consume step without the token ever appearing in a URL, a proxy log or a referrer header. Returns no body — send the browser to the consume endpoint next.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/auth/impersonate-cookie-set" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/auth/impersonate-cookie-set', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/auth/impersonate-cookie-set", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/auth/impersonate-cookie-set", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/auth/impersonate-cookie-set')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/auth/impersonate-cookie-set');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

Response: 204 No Content

Exchange an impersonation token for its grant

POST /api/v1/auth/impersonate-exchange

Verifies a short-lived impersonation token issued by the operator console and returns the grant it carries: which operator is acting, which organization they are entering, the reason recorded, and when the grant expires. The dashboard uses it to open a support session. Expired, ended, replayed and forged tokens are all rejected with the same 401, so the response cannot be used to probe which tokens exist. Every exchange is audit-logged.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/auth/impersonate-exchange" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/auth/impersonate-exchange', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/auth/impersonate-exchange", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/auth/impersonate-exchange", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/auth/impersonate-exchange')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/auth/impersonate-exchange');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{}

Set a new password with a reset token

POST /api/v1/auth/reset-password

Completes a password reset. Validates the single-use token from the emailed link and checks the new password against the complexity policy, then updates the credential, signs the account out of every other active session, and sends a follow-up email offering one-click revocation of the account’s API keys. The token is burned on success, so a reset link never works twice.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/auth/reset-password" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/auth/reset-password', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/auth/reset-password", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/auth/reset-password", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/auth/reset-password')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/auth/reset-password');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{}

{}

API Reference

All Endpoints

Auth API

Auth API

The SAML SSO round-trip

Revoke every API key after a password reset

Request a password-reset email

Exchange an impersonation token for its grant

Set a new password with a reset token

​Auth API

​title: “The SAML SSO round-trip” description: “Walk the four SAML steps end to end — SP metadata, SP-initiated login, the IdP’s ACS POST to the callback, and optional single logout.”

​The SAML SSO round-trip

​Consume the staged impersonation cookie

​Revoke every API key after a password reset

​Record terms and privacy consent

​Request a password-reset email

​Stage an impersonation token in a cookie

​Exchange an impersonation token for its grant

​Set a new password with a reset token

Auth API

title: “The SAML SSO round-trip” description: “Walk the four SAML steps end to end — SP metadata, SP-initiated login, the IdP’s ACS POST to the callback, and optional single logout.”

The SAML SSO round-trip

Consume the staged impersonation cookie

Revoke every API key after a password reset

Record terms and privacy consent

Request a password-reset email

Stage an impersonation token in a cookie

Exchange an impersonation token for its grant

Set a new password with a reset token