​

Orchestrate the public API surfaces

​

When public surfaces matter

​

Public-callback flow (worked sequence)

1. Create the callback server-side. Your backend (with a real API key) requests a callback — either via the queue endpoint POST /api/v1/voice/callbacks (or the disposition-callback rule on the queue), or the virtual-hold callback-in-queue flow. The creation response returns the callback id.
2. Sign a public token and hand it to the customer. The platform signs a compact HMAC token that embeds the callback id and the tenant it belongs to (the tenant schema travels inside the signed payload — it is not a query param). In the default flow the dispatch notification itself texts the caller a link like https://api.orbit.devotel.io/api/v1/public/callbacks/<token>. If you build your own “call me back” UI, generate the link the same way and hand the token to the browser.
3. The customer reads status. From the browser:
   curl https://api.orbit.devotel.io/api/v1/public/callbacks/<token>/status
   
   Returns the current state (pending, dialing, terminal). Poll it to keep the “we’ll call you back at …” card up to date.
4. The customer cancels or reschedules. Same token, same no-auth model:
   curl -X POST https://api.orbit.devotel.io/api/v1/public/callbacks/<token>/cancel
   curl -X POST https://api.orbit.devotel.io/api/v1/public/callbacks/<token>/reschedule \
     -H "Content-Type: application/json" \
     -d '{"at": "2026-10-02T14:00:00Z"}'
   
   Both mutations are guarded: a callback already dialing or in a terminal state is never altered, and a re-tap of cancel returns “already canceled” instead of an error. A 404 (CALLBACK_NOT_FOUND) means the row is gone or the token doesn’t validate — render a friendly expired-link page, not a retry loop.
5. Render the landing page if you don’t want to build UI. GET /public/callbacks/{token} (without a suffix) returns a self-contained HTML status page with cancel/reschedule buttons — suitable as the direct tap target of the SMS link.

​

Consent capture

1. Fetch the tenant’s published form config so your page renders the tenant’s own branding, copy, and allowed channels:
   curl https://api.orbit.devotel.io/api/v1/public/consent/<tenantId>/config
   
   Unknown or disabled tenants return enabled: false with empty branding — the endpoint cannot be used to enumerate which tenant ids exist. Treat enabled: false as “render your own fallback form,” not as an error to surface.
2. Post the consent decision:
   curl -X POST https://api.orbit.devotel.io/api/v1/public/consent \
     -H "Content-Type: application/json" \
     -d '{
       "tenantId": "<tenantId>",
       "address": "+14155551234",
       "channels": ["sms"],
       "granted": true,
       "proofToken": "<token-from-the-recipient-address>"
     }'
   
   granted: false (opt-out) is one-click and needs no proof token. granted: true (opt-in) is only recorded as opted_in when the signed proof token delivered to the recipient’s own address (email or phone) validates — this is what stops someone from opting in a number they don’t control. The response lists one consent-record id per channel written.

​

Surveys and CSAT

# Recipient opens the page (verify the token, render the form)
curl https://api.orbit.devotel.io/api/v1/public/surveys/<token>

# And submits
curl -X POST https://api.orbit.devotel.io/api/v1/public/surveys/<token>/submit \
  -H "Content-Type: application/json" \
  -d '{"score": 9, "comment": "Fast pickup"}'

curl -X POST https://api.orbit.devotel.io/api/v1/public/conversations/<token>/csat \
  -H "Content-Type: application/json" \
  -d '{"score": 5, "comment": "Resolved in one call"}'

​

Help-center search

curl "https://api.orbit.devotel.io/api/v1/public/help/search?org=<orgSlug>&q=refund%20policy"

​

Discovery surface: .well-known for external agents

• GET /public/.well-known/jwks.json — the EdDSA (Ed25519) JWK Set that verifies Orbit’s A2A agent identity tokens and signed AgentCards. Public key material only; an empty keys array means signing isn’t provisioned yet.
• GET /public/.well-known/ans/registry/lookup — Agent Trust Registry lookup: pass ?org=<slug> plus one of ans URI, agentId, or E.164 phone to get the tenant’s brand-identity verification status, STIR/SHAKEN attestation tiers, and the agent’s scoped capability surface. Unknown orgs and disabled lookups collapse to the same 404.
• GET /public/mcp/.well-known/mcp.json — the hosted MCP server manifest (Streamable-HTTP transport at /api/v1/mcp) so MCP-aware agent hosts auto-configure without a hand-shared URL.
• GET /public/.well-known/http-message-signatures-directory — the public-key directory for verifying HTTP Message Signatures on Orbit-signed outbound requests.

​

Token model and scoping guarantees

• The token is the whole grant. It is base64url(payload).base64url(HMAC-SHA256(secret, payload)). The payload carries the resource id and the tenant it belongs to, so a browser cannot reach across tenants by editing the URL — any tamper fails a constant-time HMAC compare. There is no session, no cookie, no tenant plugin.
• Hold the token in the URL, nowhere else. Deliver it in the SMS/email link (or in the DOM of your served page) and let the customer carry it back. Do not log it, do not mirror it into your analytics, and do not persist it in your own database — you already have the callback id server-side. If the link leaks, the blast radius is one resource’s lifecycle (cancel/reschedule), not org data.
• Expired or forged token → 404/403, never a data leak. A bad token on the callback surface returns CALLBACK_NOT_FOUND (404); survey submit returns 403. Generate the link, hand it over, then forget it.
• Scoping is per-link. One token maps to one callback, one survey invitation, one conversation rating. A customer holding a valid token can act on that resource only — never on the org’s list of callbacks, other customers, or queue configuration.

​

What NOT to call from the browser

• Never put a dv_live_sk_* key in browser code. Anyone with devtools can read it and drain your wallet. Server-only.
• Org-scoped siblings of the same resource stay server-side. GET/DELETE /voice/callbacks/{id}, PATCH /voice/callbacks/{id}, queue configuration, survey definitions, consent-management settings — these leak or mutate org data. The public token endpoints exist precisely so the browser does not need the org-scoped route; don’t “simplify” by exposing the keyed one.
• Don’t proxy-re-log the public endpoint. If you must mediate (e.g. embedding the status check in a logged widget), call the public endpoint from the browser directly — bouncing it through your backend adds latency and gains nothing, because the token is already the ceiling of access.

​

FAQ