SIPSTACK Support
Overview
SIPSTACK API 2026-06-10
Section titled “SIPSTACK API 2026-06-10”The SIPSTACK REST API. There are two distinct surfaces — see the API Overview for how to choose:
| Surface | Auth | Stability |
|---|---|---|
Developer API (/api/v2/...) | API key (x-api-key header) | Stable, server-to-server |
API key & webhook management (/api/api-keys, /api/webhooks) | Portal session (Bearer JWT) | Documented, owner/admin only |
Portal API (/v2/portal/...) | Portal session (Bearer JWT or portal_token cookie) | Powers Switchboard — may change without notice |
Base URL: https://api.sipstack.com
The Developer API (/api/v2/...) spans all three SIPSTACK products, each
under its own path:
| Product | Path | What you can do |
|---|---|---|
| Flare (messaging) | /api/v2/messages, /api/v2/contacts, /api/v2/flare/* | Send SMS/MMS (transactional / A2P), read message history, full contacts CRUD + search, contact opt-out/opt-in, A2P campaigns, and contact lists / segments |
| Nova (calling) | /api/v2/nova/* | Click-to-call, read call history (CDRs), numbers, extensions, voicemails, and per-call recordings + transcription |
| Aura (AI voice agent) | /api/v2/aura/* | Read agent calls with transcript, summary, and outcome; enumerate voice agents and manage each agent’s knowledge-base tags |
| Numbers (DID self-service) | /api/v2/numbers/* | Search available numbers, view your DID inventory, register E911, and (gated) order a number |
| (cross-product) | /api/v2/webhooks, /api/v2/events, /api/v2/me | Manage webhook endpoints, discover the event catalog, identify your key |
API access is subscription-tier gated (#3226). A key on a plan without API
access (Flare requires Ultra; Nova requires Enterprise) gets a 403
with a plain “upgrade to access the API” message. The tier gate is enforced
per endpoint by product: Flare/contacts/numbers endpoints check the account’s
Flare API entitlement (Ultra+), Nova/Aura endpoints check the Nova API
entitlement (Enterprise). Flare SMS is transactional / A2P; Nova SMS is
peer-to-person (P2P) and is not exposed for programmatic sending.
Scopes gate which operations a key can call. Every endpoint below declares
the scope it needs (e.g. sms:read, calls:write, numbers:read); a key must
hold that scope (or the wildcard *) or the request is denied with 403
insufficient_scope. Enforcement is fail-closed: a key with no scopes (an
unscoped or legacy key) satisfies no scoped endpoint and is denied — it is not
treated as full access. See
API Keys for the full scope list.
The Portal API endpoints included here document the core authentication and read flows as they behave today. They evolve with the product; build durable integrations against the Developer API and treat portal endpoints as best-effort. There is no partner API today — partner operations (statements, earnings, customers) are available in the Partner Portal UI only.
Authentication
Section titled “ Authentication ”bearerAuth
Section titled “bearerAuth ”Portal session JWT from POST /v2/portal/auth/login. Browser clients
receive the same token as an httpOnly portal_token cookie and may
authenticate with the cookie instead of the header.
Security scheme type: http
Bearer format: JWT
apiKeyAuth
Section titled “apiKeyAuth ”Long-lived API key (sk_live_... / sk_test_...) for the Developer
API. Test keys are rejected in production.
Scopes. A key carries a set of scopes (e.g. sms:send, sms:read,
calls:read, calls:write, contacts:read, contacts:write,
aura:read, aura:write, numbers:read, numbers:write,
webhooks:manage) or the wildcard * for full access. Scopes are
enforced per endpoint and are fail-closed: each operation states the
scope it requires, and a key that does not hold that scope (or *) is
denied with 403 insufficient_scope. A key with no scopes — including an
unscoped or legacy key — satisfies no scoped endpoint; it is not treated
as full access.
Expiry. A key may be minted with an expiry (30 / 60 / 90 / 365 days)
or set to never expire. Requests presenting an expired key get 401
with a distinct “API key has expired” message — rotate the key.
Keys are created and managed in Switchboard at Account → Integrations → API keys, or via the management API. See API Keys.
Security scheme type: apiKey
Header parameter name: x-api-key