Authentication

Every Surge API request requires an API key. Pass it as a Bearer token (preferred) or via HTTP Basic auth. Keys are scoped to a platform, and account-specific resources are addressed by the account ID in the request path.

Create and manage API keys

All requests to the Surge API require an API key. You create and manage keys in the dashboard at Settings → API Keys.

There are two key types:

Demo keys have the same capabilities as live keys, except sends route through the shared demo number and are capped at 25 messages.

Authenticate with a Bearer token

Pass your API key as a bearer token in the Authorization header:

Authorization: Bearer sk_live_your_api_key_here

Alternative: HTTP Basic auth

You can also authenticate using HTTP Basic auth with the API key as the username and an empty password. Most HTTP clients support this format.

curl https://api.surge.app/accounts/{account_id}/messages \
  -u "sk_live_your_api_key_here:"

Bearer auth is preferred. Basic auth is supported for compatibility with tools that don't have a dedicated bearer token field.

Scope requests to an account

API keys are scoped to a platform: they can access all accounts under that platform. Account-specific resources are scoped by the account ID in the request path:

GET /accounts/acct_01jrzhe8d9enptypyx360pcmxj/messages
POST /accounts/acct_01jrzhe8d9enptypyx360pcmxj/messages

A single platform API key can create and manage multiple accounts, send messages from any of them, and read data across all of them.

Authentication errors

View API request logs

All authenticated API requests are logged. You can view them in the dashboard under Settings → API Logs. Logs include the method, path, response status, and response time for each request.