Connected Apps and Integrations

Outside software reaches your WARP account through the API at https://api.warp.ringer.tel. There are two ways to authenticate it, and which one you use depends on what kind of software it is.

Creating, rotating, and revoking API keys is covered step by step in Team, Roles, API Keys, and Account Security. This guide covers the choice between the two credential kinds, and the authorized-application flow that guide does not cover.

Two Credential Kinds

An API key is a long-lived secret that belongs to your customer account, not to a person. Use it for anything that runs unattended: your own backend, a script, a scheduled job, a CI pipeline, a command-line tool. It is presented as a bearer token:

$ curl https://api.warp.ringer.tel/v1/trunks \
    -H "Authorization: Bearer $WARP_API_KEY"

Live keys begin rk_; test keys begin rk_test_. The rk_test_ prefix is a label for your own bookkeeping — it is not a sandbox, and a test key acts on real data.

An authorized application is a grant that belongs to you, made by approving a named application in the portal. Use it for interactive software you sign in to rather than configure with a secret — a desktop AI assistant connecting to WARP's hosted assistant endpoint at https://mcp.warp.ringer.tel/ is the usual case. Nothing is copied and pasted; the application receives a short-lived token of its own.

Rule of thumb: if the software has a config file you would paste a secret into, use an API key. If it has a "Connect" or "Sign in with…" button, let it take you through the approval flow.

Both kinds work against the same /v1/* endpoints and are both bound to one customer. Three areas are session-only and reachable from neither: the Buzz assistant, your own profile and session endpoints, and the sign-in endpoints themselves.

Approving an Application

The application starts the flow. You are sent to GET /oauth/authorize, which checks the request and hands you to the portal's approval page at /oauth/consent.

To approve you must be signed in and two-factor verified. The page names the application and lists the exact permissions the approval would grant, resolved for your account and the customer you are currently working in. Read that list — it is the whole of what you are handing over. Approve or deny.

On approval the application receives a single-use code, valid for a few minutes, which it immediately exchanges at POST /oauth/token for its own tokens. Access tokens are short-lived — about an hour — and the application renews them quietly with a refresh token that rotates on each use and lasts up to 30 days. A refresh token that has already been rotated is refused if it is presented again, so a stolen copy stops working the moment the real application renews.

If you are working across more than one customer, choose the right one before you approve. The grant is bound to the customer that was active at the moment of approval, and the approval page has no customer picker of its own. Accounts that can act for several customers must set one first — otherwise the page reports that an active customer context is required.

A developer building their own client registers it at POST /oauth/register and can read the server's capabilities from GET /.well-known/oauth-authorization-server. Proof Key for Code Exchange is required; there are no client secrets.

What an Authorized Application Can Reach

An approved application acts with your permissions for that one customer, minus three things that are removed from every grant no matter what your role holds:

• Administrative permissions. Anything beginning admin: is stripped. An approved application can never reach an administrative screen or endpoint, even when the person who approved it is Ringer staff.
• API-key management. api_keys:write is stripped, so an application can never mint, rotate, or revoke keys. Key management stays in the portal.
• Buzz. buzz:use and buzz:write are stripped. The in-portal assistant is not available to outside software.

Everything else you hold is passed through: your trunks, numbers, porting, messaging, billing, and call-record permissions, exactly as your role granted them at the moment you approved. The grant is a snapshot, not a live reflection of your role — if your permissions are narrowed later, an application you already approved keeps the ones it was given. Narrowing a role is therefore not a way to cut an application back; revoke the grant instead.

API keys carry the same three exclusions, enforced when the key is created: a key may only be given permissions the person creating it already holds, never an admin: permission, never api_keys:write, and never Buzz.

Reviewing and Revoking

API keys are listed at Settings → API keys (/settings/api-keys) with their prefixes, permissions, and audit history. Rotate or revoke them there. The full secret is shown once at creation and never again.

Authorized applications have no list of their own in the portal today — /settings/oauth simply forwards to the API keys page. To withdraw a grant, disconnect WARP from inside the application. An application that follows the standard calls POST /oauth/revoke when you do, and the grant stops working immediately — WARP checks the grant on every request, so revocation does not wait for a token to expire. If the application offers no disconnect, or it was approved by mistake and you cannot reach it, contact support.

Two things that are easy to get wrong:

• Approved applications do not appear under Settings → Sessions. That page lists your portal sign-ins only.
• Signing out, revoking a session, or changing your password does not revoke an authorized application or an API key. Those are separate credentials with separate lifetimes. If you are responding to a suspected compromise, clear all three: change the password, revoke the sessions, and revoke every key and grant.

Revoking one kind never revokes the other, and neither follows a role change. When someone leaves your organization, removing them from the team does not by itself stop an application they had authorized, and any API key they created belongs to the customer and keeps working until someone revokes it. Revoke both explicitly as part of offboarding.

Practical Notes

• Give each integration its own credential. Shared credentials cannot be revoked without breaking something else.
• Select only the permissions an integration needs. A reporting script needs read permissions and nothing more.
• Add an IP allowlist to an API key when the integration runs from stable addresses.
• Store key secrets in your own secret manager or environment, never in a repository or a ticket.
• Rotate keys on a schedule, and immediately if a secret may have been exposed.
• If a request comes back 401 or 403, the usual causes are a revoked or expired credential, a missing permission, or a source address outside the key's allowlist.