API Keys

API Keys

API keys give your applications long-lived access to the SIPSTACK Developer API without a user login. They are sent in the x-api-key header:

curl -s -X POST https://api.sipstack.com/api/v2/messages/send \
  -H "x-api-key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14165550100", "message": "Hello" }'

Key Facts

Format	sk_live_... (production) or sk_test_... (test — rejected by the production API)
Header	x-api-key (not Authorization: Bearer)
Scopes	A key grants a chosen set of capability scopes (or full access *)
Expiry	Optional — 30 / 60 / 90 / 365 days, or never
Storage	SIPSTACK stores only a SHA-256 hash — the full key is shown once at creation
Tracking	Last-used time is recorded on every authenticated request
Plan gating	API access is a subscription-tier feature (Flare: Pro and above; Nova: Pro and above); without it, requests return 403

Scopes

Each key carries the set of capabilities it is allowed to use. Grant only what an integration needs — a leaked read-only key can’t send messages or place calls. Calling an endpoint without its required scope returns 403.

Scope	Grants
sms:send	Send outbound SMS/MMS and create/send Flare campaigns
sms:read	Read message history, delivery status, and campaign status/analytics
calls:read	Read call detail records (CDRs), numbers, extensions, voicemails, recordings, and transcriptions
calls:write	Place click-to-call (Nova) calls
contacts:read	Read contacts, contact lists, and list membership
contacts:write	Create/update/delete contacts, opt contacts in/out, and manage contact lists
aura:read	Read Aura AI voice-agent calls (transcript, summary, outcome) and voice agents / KB tags
aura:write	Manage a voice agent’s KB tags; trigger outbound Aura calls (not generally available)
numbers:read	Search available numbers and read your DID inventory
numbers:write	Register E911 and order numbers (ordering is available by default; operators can disable it with the NUMBERS_PUBLIC_ORDER_ENABLED platform kill-switch)
webhooks:manage	Create, update, and delete webhook endpoints
*	Full access — every capability, including ones added later

Each endpoint in the API Reference states the scope it requires. A key must hold that scope (or the wildcard *) or the request is denied with 403 insufficient_scope — this is enforced per endpoint, independently of the subscription-tier gate below.

Note

Scope enforcement is fail-closed. A key with no scopes — including an unscoped or legacy key — satisfies no scoped endpoint and is denied; it is not treated as full access. Grant a key * (or the specific scopes it needs) for it to call scoped endpoints.

Expiry

A key can be set to expire after 30, 60, 90, or 365 days, or to never expire. A request presenting an expired key is rejected with 401 and a distinct “API key has expired. Generate a new key to restore access.” message — mint a fresh key (see rotating keys).

Managing Keys

Manage keys in Switchboard at Account → Integrations → API keys — create a key (name + scopes + expiry), view usage, and revoke, regenerate, or delete keys, all from the UI. The full key value is shown once, at creation; copy it immediately.

Who can manage keys: account owners can always create, revoke, regenerate, and delete API keys. Other team members can too once an owner grants them the Manage API Keys & Webhooks permission (see below) — that one permission covers the Switchboard page and the API alike.

Which plans include API keys: API keys are included with Flare Pro and above. If your plan doesn’t include API access, the API keys page shows an upgrade prompt with a View plans button in place of the Create key button. Any keys you already have stay listed, so you can still revoke or delete them.

You can also manage keys through the API, authenticated with a portal session that carries the Manage API Keys & Webhooks permission (flare.api_keys.manage) — organization owners and SIPSTACK staff always have it (see Authentication). It is its own permission, deliberately: creating a key issues a long-lived bearer credential for your whole API surface, so it is not bundled with general org-settings access and is off by default in every role preset. Grant it explicitly to a permission group:

Action	Endpoint
List keys	GET /api/api-keys
Create a key	POST /api/api-keys with { "name": "CRM Integration", "environment": "production" }
Revoke a key	POST /api/api-keys/{id}/revoke
Regenerate a key	POST /api/api-keys/{id}/regenerate
Delete a key	DELETE /api/api-keys/{id}
Usage stats	GET /api/api-keys/usage

The full key value is returned only in the create/regenerate response — copy it immediately and store it securely. Revocation takes effect on the next request.

Tip

If you’d rather not script the provisioning, open a support ticket and the team can issue a key for your organization.

Rotating Keys

1. Call regenerate on the key (or create a new key alongside the old one).
2. Update your application with the new value.
3. Confirm traffic on the new key (last-used updates), then revoke the old one if you created a separate key.

Rotate keys after any suspected exposure or relevant team departure; every 90 days is a reasonable default policy.

Security Best Practices

• Never store keys in source code — load them from environment variables or a secrets manager (AWS Secrets Manager, Vault, CI secrets).
• Never expose keys client-side — no browser JavaScript, no mobile app bundles, no public repos. Proxy through your own backend.
• One key per integration — a compromised integration can then be revoked without breaking the others.
• Watch last-used — a key that’s active when its integration is supposedly idle deserves investigation.