Scopes & Permissions
Every integration runs on a scoped token with role ceilings: viewers read, operators propose, owners decide — and payments, cancellation and number transfers are impossible through the API by design. Coming soon.
Frequently Asked Questions
What scopes can an integration hold?
A fixed, readable list: onboarding read/write/handoff, service read/provision/modify, usage read, config read/backup, and demo read/configure. There is no payment scope, no token-management scope and no cancellation scope — those capabilities have no API surface at all.
Can an integration cancel my service or transfer my number away?
No — denied by design, at the platform level, even for the account owner. Cancelling a service or transferring a number out is a browser-only action with fresh multi-factor authentication. No token, tool or scope reaches it.
Who can approve a change an integration prepared?
A person. The prepare step produces a bound preview that expires after five minutes; confirming it requires an approval reference issued through the platform to a human. An integration cannot approve its own change.
What can a viewer-scoped token do?
Read. The viewer role ceiling is read-only across every scope — an integration running as a viewer cannot change configuration, no matter which scopes were requested for it.
How do role ceilings and scopes interact?
A token holds scopes; the person it acts for holds a role. The effective permission is the overlap — an operator with service:modify can still only carry out non-financial configuration changes, because money and membership are owner-only and browser-only.
When does this take effect?
With the platform integrations release, coming soon. The changelog page records the launch.
Status: coming soon. The scopes and roles model ships with the platform integrations release. This page documents the designed model from the product specification; the changelog announces launch.
The model in one paragraph
Every integration credential is a personal access token with explicit scopes (what it may touch) acting for a person with a role (how much they may do). The effective permission is the overlap of the two — and on top of both sit platform-level denials that no scope, role or token can override: payments, cancellation and number transfer-out have no API path at all.
The scope list
| Scope | Allows |
|---|---|
| onboarding:read | Read sign-up / activation progress |
| onboarding:write | Fill in details and select plans during sign-up |
| onboarding:handoff | Start the platform-handled payment-card flow during sign-up (card details never pass through the integration) |
| service:read | List services, numbers and current configuration |
| service:provision | Stage a new service for approval |
| service:modify | Stage configuration changes for approval |
| usage:read | Pull rated call records |
| config:read | Read configuration and snapshots |
| config:backup | Export configuration snapshots for backup |
| demo:read / demo:configure | Use the 7-day demo environment (synthetic — no real calls, no credit) |
Notably absent: payment.charge, token.manage, cancel, admin. These are
not unassigned scopes waiting for a request — they do not exist in the platform.
Creating a token with an unknown or dangerous scope name is refused, so a typo can
never mint an over-privileged credential.
Role ceilings
| Role | Ceiling | |---|---| | Viewer | Read only, everywhere. A viewer-scoped integration cannot change configuration. | | Operator | Configuration and non-financial proposals — prepare changes, never move money or membership. | | Owner | The only role that manages payments, members, tokens and standing grants — and those are browser-only actions with fresh multi-factor authentication. |
The ceilings are enforced by the platform, not by hidden buttons: an operator's integration that attempts a payment-shaped action is refused server-side, whatever its scopes say.
Prepare → confirm: no self-approval
Any change to a service or configuration runs in two steps:
- Prepare — the integration submits the intended change. The platform returns a bound preview: the identity, account, client and grant it is tied to, the target configuration, and a digest of the quote where costs are involved. The preview expires after five minutes and is bound to exactly that context — it cannot be replayed elsewhere.
- Confirm — applying the preview requires an approval reference issued by the
platform to a human being. An integration cannot pass
approved: true; there is no flag, only an approval created by a person who saw the preview.
The same gate protects onboarding: provisioning a paid service waits for the sole admin confirmation, and unsupported products (porting, premium numbers, transfers) become a platform-guided task rather than something an API caller can trigger.
What is impossible by design
Some capabilities are excluded from the API surface entirely — not deprecated, not gated, absent:
- Cancelling a service, closing an account, surrendering a number.
- Transferring a number out to another carrier.
- Charging payments or changing payment methods outside the platform-handled flows.
- Creating or managing tokens (that is the owner, in the browser).
- Anything on the separate admin platform — customer credentials and grants carry no authority there.
These boundaries hold even for the account owner's own token. Automation is for reading, drafting and proposing; decisions that change what your business pays for or where your number lives are human, browser-side actions with fresh MFA.
OAuth for third-party apps (launch detail)
Integrations built for other customers authenticate through OAuth 2.0 with the authorization-code flow and PKCE: state validation, exact redirect matching, one-use codes, one-hour access tokens, and refresh tokens that rotate on a capped lifetime — reuse detection revokes the entire refresh family. Details land on the changelog at launch.
Where this fits
- MCP server — AI assistants run under exactly this model.
- Personal access tokens — the credential lifecycle.
- API authentication — today's Bearer tokens.
Part of the Simple Telecom API.