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"), and optionally set an expiration date.

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. All requests must use HTTPS.

curl

curl -X GET https://api.joltsms.com/v1/numbers \
  -H "Authorization: Bearer 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())

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. API keys 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}` }