​

Connected Apps (OAuth scoped access)

​

Why a scoped app instead of an API key

• The customer reviews a consent screen listing each capability before they install.
• The installed token is capped at the developer role even with write scopes — admin, the * wildcard, and anything billing-related are never grantable to a third-party app.
• Read scopes resolve to viewer; write scopes resolve to developer. Both the consent preview and the tokens themselves enforce that cap.
• A closed catalog of scopes means your scope parameter is validated against a fixed list, and anything outside it is rejected up front rather than partially granting.

​

Get the manifest and the scope catalog

1. Download app manifest — generates orbit-<your-org>.oauth-app.json, a deterministic client-registration document pre-wired to your org’s API host. It declares the authorization-code + PKCE flow metadata (authorisation, token, and revocation endpoints; S256 code-challenge method; token-endpoint auth via client_secret_basic or client_secret_post) plus a placeholder clientName, redirectUris, logoUri, and homepageUri for you to replace, and embeds the full scope catalog. The manifest embeds no credential — it is a definition document you submit to list your app, not a token.
2. Grantable scopes — the closed catalog below the download button. Tick scopes to build the consent request; sensitive scopes (account settings) are flagged with a warning icon.
3. Consent screen preview — renders exactly what an installing customer will see for the selected scopes, and flags any scope outside the catalog that would be rejected.

# The closed scope catalog, with consent copy
curl https://api.orbit.devotel.io/api/v1/developers/oauth/scopes \
  -H "X-API-Key: dv_live_sk_your_key_here"

# Preview the consent screen rows for a scope string
curl "https://api.orbit.devotel.io/api/v1/developers/oauth/consent-preview?scope=messages:read%20contacts:write" \
  -H "X-API-Key: dv_live_sk_your_key_here"

# Download the client-registration manifest
curl https://api.orbit.devotel.io/api/v1/developers/oauth/manifest \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -o orbit-my-org.oauth-app.json

​

The grantable catalog

• messages, contacts, conversations, campaigns, flows, agents, numbers, voice, video, inbox, templates, webhooks, knowledge — :read and :write pairs.
• analytics — :read only (usage and delivery analytics; there is no write scope).
• settings — :read only, and flagged sensitive because it touches account and organization settings.

​

Initiate the authorization-code flow from your product

GET /api/v1/oauth/authorize
  ?client_id={your client_id}
  &redirect_uri={one of your registered redirect URIs}
  &response_type=code
  &scope=messages:read%20contacts:read
  &code_challenge={base64url(SHA256(code_verifier))}
  &code_challenge_method=S256
  &state={random, stored client-side}

​

Exchange the code for tokens

curl -X POST https://api.orbit.devotel.io/api/v1/oauth/token \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=authorization_code" \
  -d "code={code from the callback}" \
  -d "redirect_uri={same redirect URI}" \
  -d "code_verifier={original verifier}"

# Use the access token like any Bearer token
curl https://api.orbit.devotel.io/api/v1/messages?limit=10 \
  -H "Authorization: Bearer {access_token}"

​

Refresh and revoke tokens

curl -X POST https://api.orbit.devotel.io/api/v1/oauth/token \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=refresh_token" \
  -d "refresh_token={current refresh token}"

• Your side (server-to-server): POST the token to the revocation endpoint the manifest declares. Revoking the refresh token ends the session cleanly; also revoke the orphaned access token if you hold both.
• Customer side (tenant-controlled): disconnecting your app in the customer’s dashboard revokes the installation’s tokens themselves — the next API call with a revoked token returns 401. That’s the customer’s kill switch; don’t treat it as an error on your side, treat it as an uninstall.

# Revoke a token you hold (RFC 7009 shape)
curl -X POST https://api.orbit.devotel.io/api/v1/oauth/revoke \
  -u "{client_id}:{client_secret}" \
  -d "token={access or refresh token}" \
  -d "token_type_hint=refresh_token"

​

Pick scopes the least-privilege way

1. List the endpoints your app calls in production, grouped by resource family and verb.
2. Map each family to the narrowest access class — prefer :read everywhere a :write isn’t strictly required. If you send campaigns through Orbit but never construct them in your product, campaigns:read is enough.
3. Mark data that’s read and joined back in (e.g. analytics you mirror to your warehouse) as :read — not because you lack write access to the platform’s mutations, but because the customer’s review step is cheaper when the sensitive surface is smaller.
4. If your app later needs an extra scope, bump the request string and re-prompt — newer installs just see an updated consent screen; existing installs retain what they approved.

​

Frequently asked questions

​

Does my app need its own Orbit account to be listed?

​

Can a customer install the same app in two orgs?

​

What happens to in-flight tokens when a customer revokes my app?

​

We use the MCP server instead of raw REST. Do scopes matter there?

​

See also

• Developer Portal — the console, try-it sandbox, key governance, webhook debug, and OAuth manifest downloads this page plugs into
• Authentication — API-key formats, role ranges (viewer → developer here), and rotation
• API Integration — base URL, sandbox test mode, error codes, and rate limits if you’re calling the API itself
• Security — org-level session, key, and webhook security hygiene
• Rate limits — what to design around when your installed app fans out