Authentication

Authentication

All TextBubbles API requests require a Bearer token in the Authorization header.

Bearer Token

Authorization: Bearer tb_xxxxxxxxxxxxx

Example request:

curl https://api.textbubbles.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Response

Requests without a valid token receive a 401 Unauthorized response:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header"
  },
  "requestId": "req_xyz"
}

API Key Format

API keys use the prefix tb_ followed by a unique identifier. Store your API key securely and never expose it in client-side code.

Rate Limiting

Each API key has its own rate limits. When exceeded, you’ll receive a 429 Too Many Requests response with a Retry-After header:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please retry after 60 seconds."
  },
  "requestId": "req_xyz"
}

Implement exponential backoff when handling rate limits:

async function sendWithRetry(payload, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch('https://api.textbubbles.com/v1/messages', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(payload),
    });
 
    if (response.status !== 429) {
      return response.json();
    }
 
    const retryAfter = response.headers.get('Retry-After') || Math.pow(2, attempt) * 10;
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  }
 
  throw new Error('Max retries exceeded');
}

Request IDs

Every API response includes a requestId field. You can also pass your own via the X-Request-Id header. Log these for debugging and include them when contacting support.

Best Practices

  • Store API keys in environment variables, never in source code
  • Use different API keys for development and production
  • Rotate keys periodically via the admin API
  • Monitor usage via GET /v1/admin/usage
Getting StartedSend Messages