Give an agent selected access
The token owner chooses its permissions. Every request is limited to the intersection of those choices and the owner’s current company permissions. A token never inherits the Owner role.
Create and store a token
- Open Security and access → Personal access tokens → Create token.
- Name the integration, grant the needed resource families and choose View or Manage. Reports are available only with company-wide Workspace access.
- Choose 1, 7, 30 or 90 days. Confirm your password and a fresh authenticator code.
- Copy the token and company ID. The secret is displayed once; only its hash is stored.
Store the secret in a secret manager and inject it into the agent’s HTTP client. Do not put it in prompts, query strings, source code or shared logs. Up to 20 active tokens are allowed per owner. Token creation requires the browser security flow.
Make a read-only request
Use the Admin host for company configuration and the Workspace host for reports. Both use /api/v1. Send the selected company’s UUID in X-Telephony-Company. Do not send browser cookies.
# Load OVERTONE_TOKEN and OVERTONE_COMPANY_ID privately into the environment.
curl --fail-with-body --silent --show-error \
https://admin.overtone-test.sayram.systems/api/v1/session \
-H "Authorization: Bearer $OVERTONE_TOKEN" \
-H "X-Telephony-Company: $OVERTONE_COMPANY_ID"A successful response has {"data": ..., "error": null}. Session introspection returns the current effective grants, user ID, company ID and token ID. It does not return the token secret. A token with only Reports access must use the Workspace host even for introspection.
curl --fail-with-body --silent --show-error \
https://admin.overtone-test.sayram.systems/api/v1/settings/users \
-H "Authorization: Bearer $OVERTONE_TOKEN" \
-H "X-Telephony-Company: $OVERTONE_COMPANY_ID"Permission families and routes
All paths below are relative to /api/v1. View permits reads; Manage adds the corresponding writes. Existing resource validation and optimistic revisions still apply. This API exposes company dashboard operations.
| Permission | Resource paths | Behavior |
|---|---|---|
| People | /settings/users, employee extension, calling-number and inbox-grant subpaths | Manage edits employee assignments. Password reveal/reset endpoints are unavailable to tokens. |
| Devices | /settings/client, /settings/client-users, /settings/sip-status, /settings/device-sessions | Manage may revoke employee device sessions and edit client policies. |
| Routing | /routing, /routing/options, /routing/history, /routing/draft, /routing/validate, /routing/publish, /routing/rebase | Saving a draft and publishing it are separate operations. Publish changes call handling. |
| Mailboxes | /mailboxes and mailbox commands | Configuration only; no employee message-content access. |
| Caller experience | /schedules, /audio and their commands | Manage edits schedules and greeting assets. |
| Conferences | /conferences and conference commands | The same conference permissions and validation as Admin. |
| Company | /company-profile | Company profile settings. |
| Messaging | /messaging, /settings/messaging-readiness | Account campaign setup and number readiness; no SMS sending endpoint here. |
| Users and access | /access, /users/invite, /invitations, /users/:id/status | Owner-only operations still require a company Owner. Grants and account re-enabling cannot exceed the token’s effective access. |
| Reports | /reports subpaths on Workspace | Scope can only narrow the owner’s scope. View includes reports and exports; Manage also edits saved report views. |
| Number purchases | /number-purchases subpaths on Admin | Manage can buy numbers and incur charges. |
The machine-readable route and contract reference is generated from the registered gateway routes and shared schemas. Unsupported paths return 404 or 403.
Writes, retries and costs
Send JSON with Content-Type: application/json. For commands requiring requestId, generate one UUID for the intended operation and reuse it only when retrying that identical operation. A changed operation needs a new UUID. For revisioned writes, read the current revision and submit the expected revision. On 409, refresh the resource and resolve the conflict before trying again.
Do not blindly retry a timed-out purchase, invitation or publication. Read its result/history first; the server may have committed it before the connection failed. Invitations can send email. Number purchase permissions can incur one-time and recurring charges. Use mocked provider tests for development.
Errors and request limits
| Status | Action |
|---|---|
| 400 | Correct the request body, company header or mixed browser-cookie authentication. |
| 401 | The token is invalid, expired, revoked or no longer valid for the owner/company. Obtain a replacement through the owner. |
| 403 | The selected scope or current owner access does not permit this operation. |
| 409 | Refresh and resolve the revision or idempotency conflict. |
| 429 | Back off. Baseline limits are 120 requests/minute per token and 180/minute per IP; resource routes may impose lower limits. |
| 503 | A service is unavailable or did not confirm the operation. Read current state before retrying a write. |
Ownership and revocation
Removing an owner’s permission immediately removes it from every token on subsequent requests. Expiry, token revocation, disabling the user and changing authentication credentials prevent further token use. Permission reductions do not rewrite the original selected grants; if the owner regains a permission, that previously selected permission can become available again. Revocation is permanent.
Token operations are audited by owner and token ID, with the method and route template. Secrets are not included. Already completed operations are not undone by later revocation.
Tokens cannot create other tokens, manage personal sessions/passkeys, change interface preferences, authenticate as Ops, access another company or use employee session APIs. Account-linked memberships currently cannot create these tokens; their parent Account remains the authentication authority.