Settings API

Everything that shows up under the dashboard’s Settings tab — the organization profile, user preferences, in-app notifications, team & invites, API keys, sender IDs, single sign-on (SAML & SCIM), HIPAA controls, privacy, compliance policies, and keyword / opt-out rules. Base path: /api/v1/settings Authentication: Session JWT (most operations are admin/owner-gated).

Using the SDKs

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

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

const res = await orbit.settings.get();

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/settings")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

Organization

Method	Path	Purpose
`GET`	`/api/v1/settings/organization`	Read org profile
`GET`	`/api/v1/settings/general`	General settings
`PUT`	`/api/v1/settings/general`	Update general settings

curl "https://api.orbit.devotel.io/api/v1/settings/organization" \
  -H "X-API-Key: $ORBIT_API_KEY"

{
  "data": {
    "id": "org_a41f3c2b9d",
    "name": "Acme Logistics",
    "plan": "growth",
    "credits": 124000,
    "created_at": "2026-03-12T09:30:00Z"
  },
  "meta": {
    "request_id": "req_org_001",
    "timestamp": "2026-08-25T10:00:00Z"
  }
}

User preferences

Method	Path	Purpose
`GET`	`/api/v1/settings/preferences`	Read the calling user’s preferences
`PUT`	`/api/v1/settings/preferences`	Update preferences (theme, language, timezone)

PUT /api/v1/settings/preferences is a partial update — send only what changes:

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/preferences" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "theme": "dark", "language": "en", "timezone": "Europe/Berlin" }'

Notifications

Method	Path	Purpose
`GET`	`/api/v1/settings/notifications`	List all notifications (read and unread)
`DELETE`	`/api/v1/settings/notifications`	Permanently delete all notifications (irreversible — this does not mark them as read)
`PUT`	`/api/v1/settings/notifications/{id}/read`	Mark one as read

Team

Method	Path	Purpose
`GET`	`/api/v1/settings/team`	List team members
`GET`	`/api/v1/settings/team/activity`	Recent team activity
`POST`	`/api/v1/settings/team/invite`	Invite a new member
`PUT`	`/api/v1/settings/team/{userId}`	Change role
`DELETE`	`/api/v1/settings/team/{userId}`	Remove a member
`GET`	`/api/v1/settings/team/invites`	List pending invites
`DELETE`	`/api/v1/settings/team/invites/{email}`	Cancel an invite
`POST`	`/api/v1/settings/team/invites/{email}/resend`	Resend an invite
`POST`	`/api/v1/settings/team/accept-invite`	Accept an invite (invited user calls this)

API keys

Method	Path	Purpose
`GET`	`/api/v1/settings/api-keys`	List API keys
`POST`	`/api/v1/settings/api-keys`	Issue a new API key
`DELETE`	`/api/v1/settings/api-keys/{id}`	Revoke immediately
`POST`	`/api/v1/settings/api-keys/{id}/rotate`	Rotate (issues new + revokes old)
`POST`	`/api/v1/settings/api-keys/{id}/schedule-revoke`	Schedule revocation in the future (for safe rotation)
`POST`	`/api/v1/settings/api-keys/{id}/cancel-revoke`	Cancel a scheduled revoke

POST /api/v1/settings/api-keys returns the plaintext key once — stored with a _warning because it is never readable again. expiresIn accepts never, 30d, 90d, or 1y; allowed_ips accepts bare IPs or CIDRs (empty = unrestricted). mode: "test" activates sandbox mode (no delivery, no charges).

curl -X POST "https://api.orbit.devotel.io/api/v1/settings/api-keys" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend SMS sender",
    "type": "secret",
    "mode": "live",
    "expiresIn": "90d",
    "scopes": ["messaging.send"],
    "allowed_ips": ["203.0.113.10"]
  }'

{
  "data": {
    "id": "key_0u9k2x5m4z",
    "name": "Backend SMS sender",
    "key": "dv_live_sk_3f6c2a19d57e4b90ac12",
    "type": "secret",
    "mode": "live",
    "active": true,
    "created_at": "2026-08-25T10:02:00Z",
    "_warning": "Store this key securely. It will not be shown again."
  },
  "meta": {
    "request_id": "req_apikey_001",
    "timestamp": "2026-08-25T10:02:00Z"
  }
}

Rotate a key without taking integrations down — by default the old key keeps authenticating for a grace period (1–168 hours) while you swap it everywhere; mode: "immediate" revokes at once:

curl -X POST "https://api.orbit.devotel.io/api/v1/settings/api-keys/key_0u9k2x5m4z/rotate" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "grace_period_hours": 24 }'

The response carries the new key’s plaintext (shown once) plus the old key’s revocation cutoff. Cancel a scheduled cutoff any time before it fires with POST /api/v1/settings/api-keys/{id}/cancel-revoke.

Sender IDs

Method	Path	Purpose
`GET`	`/api/v1/settings/sender-ids`	List sender IDs
`POST`	`/api/v1/settings/sender-ids`	Register a new sender ID

Many countries require sender ID pre-registration before alpha-numeric sender IDs can be used. The full list of operations (including delete + status checks) is in the auto-generated reference below. Register an alphanumeric sender ID for SMS (≤ 11 characters on that channel) — it starts pending and becomes sendable when the destination registry approves it:

curl -X POST "https://api.orbit.devotel.io/api/v1/settings/sender-ids" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "ACME",
    "channel": "sms",
    "country": "GB",
    "description": "Delivery notifications sender"
  }'

{
  "data": {
    "id": "sid_0k7d2p4v8m",
    "senderId": "ACME",
    "channel": "sms",
    "country": "GB",
    "status": "pending",
    "description": "Delivery notifications sender",
    "createdAt": "2026-08-25T10:03:00Z"
  },
  "meta": {
    "request_id": "req_sid_001",
    "timestamp": "2026-08-25T10:03:00Z"
  }
}

Single sign-on (SAML & SCIM)

Configure enterprise SSO and directory provisioning for the org. These endpoints manage the configuration; the login and provisioning flows your identity provider calls live on the public /auth/saml/* and /scim/v2/* paths documented under Authentication.

Method	Path	Purpose
`GET`	`/api/v1/settings/saml`	Read the current SAML config (returns the certificate fingerprint, never the raw certificate)
`PATCH`	`/api/v1/settings/saml`	Upsert SAML config — SSO URL, entity ID, attribute mappings, `enabled`, `enforced`. Owner only
`POST`	`/api/v1/settings/saml/test-connection`	Probe an IdP metadata URL and suggest the SSO URL / entity ID
`GET`	`/api/v1/settings/scim`	Read the current SCIM config (returns `hasToken`, never the token)
`POST`	`/api/v1/settings/scim/generate-token`	Generate or rotate the SCIM bearer token — shown once. Owner only
`PATCH`	`/api/v1/settings/scim`	Update SCIM `enabled`, default role, and group-to-role mapping. Owner only

The SSO URL and metadata URL are validated to block requests to internal or private addresses. When you configure SAML for the first time, PATCH /api/v1/settings/saml requires an x509Cert; once one is stored, omit the field to change other settings without re-uploading it.

curl -X PATCH "https://api.orbit.devotel.io/api/v1/settings/saml" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "ssoUrl": "https://idp.example-corp.com/sso",
    "entityId": "urn:example-corp:orbit",
    "attrEmail": "mail",
    "attrName": "displayName",
    "enabled": true,
    "enforced": false
  }'

First-time setup additionally sends x509Cert (the IdP’s PEM signing certificate). The response echoes the saved configuration with cert_fingerprint_sha256 — never the raw certificate.

HIPAA controls

Manage covered-entity mode, the Business Associate Agreement (BAA) record, and the PHI access log. Reads require an admin; enabling, disabling, and BAA changes are owner only.

Method	Path	Purpose
`GET`	`/api/v1/settings/hipaa`	Read HIPAA status and configuration
`PUT`	`/api/v1/settings/hipaa`	Enable or disable HIPAA mode and set the data-retention window (30–3650 days)
`POST`	`/api/v1/settings/hipaa/reauth-challenge`	Mint a 5-minute re-auth challenge required to disable HIPAA mode. Owner only
`GET`	`/api/v1/settings/hipaa/phi-access-log`	List the PHI access log (paginated)
`PUT`	`/api/v1/settings/hipaa/baa`	Record BAA signed status, signing date, and document URL. Owner only

Disabling HIPAA mode is protected. PUT /api/v1/settings/hipaa with enabled: false returns 401 REAUTH_REQUIRED unless you first call POST /api/v1/settings/hipaa/reauth-challenge and replay the returned token in an X-Reauth-Challenge header within 5 minutes. Enabling HIPAA and retention-only updates do not require re-auth. See HIPAA compliance for the full covered-entity guide. Enable covered-entity mode and set the data-retention window; reads come back with your BAA state so you can confirm what applies before you record a signed BAA:

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/hipaa" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "data_retention_days": 365 }'

{
  "data": {
    "enabled": true,
    "data_retention_days": 365,
    "baa_signed": true,
    "baa_signed_at": "2026-07-01T00:00:00Z",
    "baa_document_url": "https://contracts.example.com/acme-baa.pdf",
    "updated_at": "2026-08-25T10:04:00Z"
  },
  "meta": {
    "request_id": "req_hipaa_001",
    "timestamp": "2026-08-25T10:04:00Z"
  }
}

To disable (owner only), first mint a re-auth challenge, then replay it in the header within 5 minutes:

RECHALLENGE=$(curl -s -X POST "https://api.orbit.devotel.io/api/v1/settings/hipaa/reauth-challenge" \
  -H "Authorization: Bearer $SESSION_JWT" | jq -r .data.token)

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/hipaa" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "X-Reauth-Challenge: $RECHALLENGE" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Privacy

Control PII redaction and transcript retention for the org. Reads are available to any member; updates are owner/admin only.

Method	Path	Purpose
`GET`	`/api/v1/settings/privacy`	Read privacy settings
`PUT`	`/api/v1/settings/privacy`	Update privacy settings

The body of PUT /api/v1/settings/privacy accepts:

pii_redaction_enabled (boolean) — mask phone numbers and email addresses on screen for viewer-tier operators. Display only; dial targets and outbound payloads still carry raw E.164.
pii_redaction_in_transcripts (boolean) — scrub PII from agent conversation turns at write time. Applies to new turns only; existing turns are not back-redacted.
transcript_retention_days (integer 1–3650, or null for no deletion) — the nightly retention job deletes agent conversations and messages older than this window.

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/privacy" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "pii_redaction_enabled": true,
    "pii_redaction_in_transcripts": true,
    "transcript_retention_days": 90
  }'

{
  "data": {
    "pii_redaction_enabled": true,
    "pii_redaction_in_transcripts": true,
    "transcript_retention_days": 90,
    "updated_at": "2026-08-25T10:05:00Z"
  },
  "meta": {
    "request_id": "req_privacy_001",
    "timestamp": "2026-08-25T10:05:00Z"
  }
}

Compliance

Per-org compliance and outbound-safety policies enforced on the send path. Each resource exposes a read (available to any member) and a write (owner only).

Method	Path	Purpose
`GET` / `PATCH`	`/api/v1/settings/compliance/policy-scan-mode`	Pre-send policy scanner mode (`strict`, `warn`, `off`)
`GET` / `PATCH`	`/api/v1/settings/compliance/unknown-marketing-policy`	Marketing-send policy for contacts whose consent state is unknown
`GET` / `PATCH`	`/api/v1/settings/compliance/consent-default-policy`	Default consent policy applied when a contact has no explicit consent record
`GET` / `PUT`	`/api/v1/settings/compliance/country-allowlist`	Outbound destination-country allowlist and the allow-all override
`GET` / `PUT`	`/api/v1/settings/compliance/fraud-caps`	Per-channel velocity and daily-spend caps, with the platform floor per channel
`GET` / `PUT`	`/api/v1/settings/compliance/channel-rate-overrides`	Per-channel outbound rate-limit overrides
`GET` / `PUT`	`/api/v1/settings/compliance/ai-turn-audit`	Toggle AI-turn audit logging
`GET` / `PATCH`	`/api/v1/settings/compliance/inbox-ai-privacy`	Toggle inbox AI auto-categorize / auto-summarize and set the spam-handling action

The country allowlist is tenant-scoped — it constrains only your own org’s outbound traffic, never another tenant’s.

Keyword & opt-out rules

Automated inbound-keyword handling and STOP/START opt-out management. Keyword-rule writes require the developer role or higher; opt-out-rule writes require an admin. Both list endpoints are paginated.

Keyword rules

Method	Path	Purpose
`GET`	`/api/v1/settings/keyword-rules`	List keyword rules
`POST`	`/api/v1/settings/keyword-rules`	Create a keyword rule
`PUT`	`/api/v1/settings/keyword-rules/{id}`	Update a keyword rule
`DELETE`	`/api/v1/settings/keyword-rules/{id}`	Delete a keyword rule

A rule matches an inbound keyword on a channel (sms, whatsapp, rcs, viber, email) with a match_type of exact, contains, starts_with, or regex, then runs an action: reply with response_text, forward to an agent_id, trigger a flow_id, or opt the contact out / back in.

Opt-out rules

Method	Path	Purpose
`GET`	`/api/v1/settings/opt-out-rules`	List opt-out / opt-in rules
`POST`	`/api/v1/settings/opt-out-rules`	Create an opt-out or opt-in rule
`PUT`	`/api/v1/settings/opt-out-rules`	Bulk update opt-out / opt-in rules (up to 100 per request)
`DELETE`	`/api/v1/settings/opt-out-rules/{id}`	Delete an opt-out / opt-in rule

Opt-out rules are keyword rules whose action is opt-out or opt-in (for example STOP and START). Set auto_reply_text to confirm the change back to the contact. See Opt-outs & suppression for how suppression is enforced at send time.

API Reference

All Endpoints

Settings API overview: org, users, keys, and SSO

Settings API

Using the SDKs

Organization

User preferences

Notifications

Team

API keys

Sender IDs

Single sign-on (SAML & SCIM)

HIPAA controls

Privacy

Compliance

Keyword & opt-out rules

Keyword rules

Opt-out rules

See also

​Settings API

​Using the SDKs

​Organization

​User preferences

​Notifications

​Team

​API keys

​Sender IDs

​Single sign-on (SAML & SCIM)

​HIPAA controls

​Privacy

​Compliance

​Keyword & opt-out rules

​Keyword rules

​Opt-out rules

​See also

Settings API

Using the SDKs

Organization

User preferences

Notifications

Team

API keys

Sender IDs

Single sign-on (SAML & SCIM)

HIPAA controls

Privacy

Compliance

Keyword & opt-out rules

Keyword rules

Opt-out rules

See also