Skip to main content

​
Choose which scopes your API key needs

The question every integration starts with is not “how do I get a key?” — it is “which scopes does this key actually need?” Devotel Orbit mints per-scope keys so a messaging worker cannot read contacts, an agent manager cannot send messages, and a leaked key loses everything except its own surface. This guide maps the three commonest integration types — messaging, CCaaS AI agents, and CDP ingestion — onto exact scope sets, gives you a naming convention that encodes the rotation schedule, shows a real scoped key working (and being rejected) over curl, and points at the request log you audit it through. For the channel-by-channel catalog of scopes, see Integrate with the Orbit REST API and the full scope picker under Settings → API Keys.

​
Read the scope table first — what each product surface needs

Every endpoint in the API integration guide’s channel table maps to exactly one scope family. Read the table before you mint, and tick only the rows your integration touches: A :write scope is not a superset of :read — the two are independent grants. Mint both when the integration writes and then reads back its own writes (a messaging worker polling GET /messages/:id for delivery status needs messages:write to send and messages:read to poll). The dashboard picker at Settings → API Keys → Create key presents the same list as checkboxes; * (wildcard) and admin are intentionally absent from the picker and only ever mintable script-side — never for a routine integration.

​
Pick the right key for the job

Three shapes cover the integrations most teams mint first. Start with the narrowest set that works — you can always re-issue with one more scope; you cannot take back the blast radius of a broad key already leaked. Messaging-only sender. A worker that POSTs sends and polls their delivery:
  • messages:write — the send itself.
  • messages:read — the status poll.
That pair is everything. No contacts, no templates, no billing. If the send is template-driven (a WhatsApp campaign fragment), add templates:read — not templates:write, unless the worker itself submits templates for approval. Agent management (CCaaS). An orchestration layer that builds, tunes, and inspects AI voice/chat agents:
  • agents:write — create, update, and configure agents.
  • agents:read — list agents and their runs.
  • knowledge:read — if the agent pulls from a knowledge base the orchestrator only queries.
  • knowledge:write — add only if the same worker also manages the knowledge base content.
Do not give an agent-management key conversations:write or messages:write by default — the agent runtime uses its own internal credential path, and a management key that can also reply as a human agent widens the leak surface without adding capability the orchestrator needs. CDP ingest. A pipeline pushing events into the customer data platform and the read side that audits it:
  • contacts:write — trait and event writes against profiles.
  • contacts:read — /cdp/profiles/*, /cdp/events/recent, and the identity-resolution reads.
The first-party event stream itself (the segment-style /cdp/v1/:ingest_id/track family) is authenticated per-ingest-source, not through this scope set — a separate ingest credential minted from the CDP source catalog. The scope pair above is what your read-side integration needs for the dashboard-shaped surfaces (GET /cdp/events/recent, GET /cdp/profiles/...). Mint them separately: the ingest credential has no API-dashboard surface and the API key has no ingest surface, so a leaked key of either kind cannot pivot into the other lane.

​
Name keys so the rotation schedule is visible

A label is the only metadata a key carries that survives to an audit log, a request-log row, or a leaked-secret paste. Encode the environment, the surface, and the rotation cadence in the name itself so anyone (including future-you at 3 a.m.) can see what a key is for and when it should retire without opening the dashboard:
Worked examples: Two rules make the convention load-bearing:
  1. One surface per key. The surface in the name must be one row of the scope table — never prod-everything. If two workers need two surfaces, mint two keys; the per-key rate-limits and budget guides below assume that shape.
  2. The rotation tag is the cohort, not the person. r2026q3 is re-minted across all keys in that cohort on the same day; a person-name (sarah-prod) survives the person leaving and outlives its meaning. Owner / admin / developer roles can rotate; the cutover is the grace flow in the next section.

​
Wire the neighboring guides as your next three steps

A scoped key is the first of four lines you should draw before production. The other three each have their own guide; set them in this order once the key is minted:
  1. Per-API-key IP allowlist — bind the key to your egress IPs so a leaked copy is useless outside your network. Cheapest possible mitigation against the paste-site scenario.
  2. Per-API-key usage limits and spend alerts — the rate limit and monthly quota that contain one noisy integration (or one compromised key) instead of your whole workspace’s throughput.
  3. Per-API-key usage budgets and threshold alerts — the dashboard tripwire: a warning badge at 80% and an exceeded badge at 100% of a budget you set per browser, layered on top of the API-level alert the whole team sees.
The fourth line — the actual key-retirement mechanics — is the rotation section below.

​
Rotate as a how-to (the lifecycle concept, applied)

The API key lifecycle and rotation concept page defines the states and the two modes; here is the cutover runbook as concrete steps against a key named prod-messaging-r2026q3:
  1. List first, so you target the right id — GET /api/v1/settings/api-keys returns labels, prefixes, suffixes, and expiry metadata; secrets are never listed.
  2. Rotate with a grace window (never immediate, for routine rotation):
  1. Copy key into your secret manager now — this response is the only place the plaintext ever appears; later reads only show the masked prefix and suffix.
  2. Deploy the new key to every integration. The old one keeps authenticating against the same scopes until oldKeyExpiresAt, so you can roll service by service (the dual-valid window is the entire point of grace mode).
  3. Confirm the cutover in request logs — once oldKeyExpiresAt passes, any request still carrying the old suffix fails 401. Grep your access logs for the old suffix ahead of the cutoff if zero surprise is the bar.
For a leaked key the same endpoint with "mode": "immediate" mints the replacement and kills the old key in one transaction — that is the incident path, not the routine one. Full mode semantics, the cutoff math, and the rotate-vs-revoke decision table live in the concept page.

​
Worked example: a messaging-only key, verified over curl

Mint a key with exactly messages:write and messages:read in the dashboard, then prove both halves — the scoped surface answers, everything else 403s:
That rejection is the whole point of scoping: the key carried no credential that /cdp/events/recent accepts, so read on those rows never happens under this key. Acceptance for any new key you mint is exactly this pair — the scoped call returns its real status, and one deliberate out-of-scope call returns 403 INSUFFICIENT_SCOPE. Do not do step 2 with the wildcard scope: a * key answers both calls and that is the smell you are verifying against.

​
Audit surface and what to grep in request logs

Verify a key is behaving the way you scoped it in the Request Logs console — filter by the API key prefix and read what it actually sent, not what you expect it sent. Three checks catch the recurring misuse patterns:
  • Scope creep. The key should only ever appear on the routes its scopes imply. A messaging-only key hitting /contacts or /cdp/events/recent means someone is re-using it for work it was never meant for — grep the request path by that key and diff against the scope table above.
  • Out-of-scope 403s. Every INSUFFICIENT_SCOPE under one key id is an attempted access the key does not have. A trickle is noise from a misconfigured client; a burst is either a worker fetching the wrong env’s key or someone probing what the key can reach. The request log records the 403 even though the caller saw only the error code.
  • The old suffix after rotation. After a grace cutover the only rows a retired suffix should produce are 401 — anything 2xx against the old suffix post-cutoff means the cutoff did not land where your runbook assumed. Re-check the oldKeyExpiresAt the rotation response returned.
For the org-wide billing-side view of the same discipline — which keys are spending, not just which keys are authenticating — pair the request log with Per-API-key spend budgets.