Authentication

Creating API Keys

Generate API keys from the JoltSMS dashboard. Each key is shown only once at creation time -- store it immediately in a secure location.

1. 1

   Open the Dashboard and navigate to Settings.

2. 2

   Scroll to the API Keys section.

3. 3

   Click Create API Key, give it a descriptive name (e.g., "CI Pipeline" or "Claude Agent"), choose an access scope, and optionally enable sensitive capabilities such as SMS replies.

4. 4

   Copy the key immediately. It will not be shown again.

Using API Keys

Pass your API key in the Authorization header as a Bearer token, or in the X-API-Key header. All requests must use HTTPS.

curl

curl -X GET https://api.joltsms.com/v1/numbers \
  -H "Authorization: Bearer jolt_sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

curl with X-API-Key

curl -X GET https://api.joltsms.com/v1/messages \
  -H "X-API-Key: jolt_sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

JavaScript (fetch)

const response = await fetch("https://api.joltsms.com/v1/numbers", {
  headers: {
    "Authorization": "Bearer jolt_sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  },
});

const data = await response.json();
console.log(data);

Python (requests)

import requests

response = requests.get(
    "https://api.joltsms.com/v1/numbers",
    headers={"Authorization": "Bearer jolt_sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"},
)

print(response.json())

API Key Scopes

API keys are scoped at creation time. Scoped keys affect number and message reads: GET /v1/numbers and GET /v1/messages only return resources allowed by the key.

Create a contract-scoped key

curl -X POST https://api.joltsms.com/v1/api-keys \
  -H "Content-Type: application/json" \
  -b "joltsms_session=YOUR_SESSION_COOKIE" \
  -d '{
    "name": "Enterprise contract automation",
    "scopeType": "ENTERPRISE_CONTRACT",
    "enterpriseContractId": "contract_uuid_here"
  }'

Create a selected-number key

curl -X POST https://api.joltsms.com/v1/api-keys \
  -H "Content-Type: application/json" \
  -b "joltsms_session=YOUR_SESSION_COOKIE" \
  -d '{
    "name": "Single workflow key",
    "scopeType": "NUMBER_SET",
    "numberIds": ["number_uuid_1", "number_uuid_2"]
  }'

API Key Capabilities

Scopes decide which numbers a key can see. Capabilities decide which sensitive write actions the key can perform. SMS replies are opt-in: a key must include the sms:reply capability to call POST /v1/messages/:id/reply.

Create a selected-number reply key

curl -X POST https://api.joltsms.com/v1/api-keys \
  -H "Content-Type: application/json" \
  -b "joltsms_session=YOUR_SESSION_COOKIE" \
  -d '{
    "name": "Support inbox replies",
    "scopeType": "NUMBER_SET",
    "numberIds": ["number_uuid_1"],
    "capabilities": ["sms:reply"]
  }'

Rate Limits

API key requests are rate-limited to 120 requests per minute. Session-based requests (from the dashboard) use standard rate limits. Every response includes headers to help you stay within bounds.

If you exceed the rate limit, the API returns a 429 Too Many Requests response. Back off and retry after the X-RateLimit-Reset time.

Error Responses

Authentication errors return standard HTTP status codes with a JSON body describing the problem.

Error response format

// 401 Unauthorized
{
  "error": "UNAUTHORIZED",
  "message": "Authentication required"
}

// 403 Session Required
{
  "error": "SESSION_REQUIRED",
  "message": "This endpoint requires browser session authentication. Bearer tokens cannot be used for this operation."
}

// 429 Rate Limit Exceeded
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded, retry in 42 seconds"
}

Session-Only Endpoints

Certain sensitive operations require session authentication (logging in through the dashboard). These endpoints return 403 Forbidden when called with an API key.

Security Best Practices

export JOLTSMS_API_KEY="jolt_sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

# Then in your code:
headers: { "Authorization": `Bearer ${process.env.JOLTSMS_API_KEY}` }