Authentication

All API requests require authentication via API key.

Base URL: https://api.texting.blue/v1

API keys

Include your API key in the x-api-key header with every request:

curl https://api.texting.blue/v1/messages \
  -H "x-api-key: tb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Key format

API keys follow the format: tb_{environment}_{32_random_chars}

• tb_live_ -- Production keys
• tb_test_ -- Test/sandbox keys (coming soon)

Creating a key

1. Go to Settings > API Keys in the dashboard
2. Click Create Key
3. Give it a name and select permissions
4. Copy the key immediately -- it's only shown once

warning

Store your API key securely. Never commit it to source control or expose it in client-side code. Use environment variables or a secrets manager.

Key permissions

When creating an API key, you can scope it to specific permissions:

Permission	Description
messages:send	Send iMessages
messages:read	Read message history
webhooks:manage	Create, update, and delete webhooks
numbers:read	List phone numbers
numbers:write	Add, remove, and update numbers
team:read	Read team info
team:write	Manage team members
*	All permissions

If a request requires a permission your key doesn't have, the API returns a 403 Forbidden error.

Revoking a key

Go to Settings > API Keys, find the key by its prefix, and click Revoke. Revoked keys stop working immediately.

Example request

curl -X POST https://api.texting.blue/v1/messages/send \
  -H "Content-Type: application/json" \
  -H "x-api-key: tb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "to": "+14155551234",
    "from": "+14155559876",
    "content": "Hello from Texting Blue!"
  }'

Error responses

If authentication fails, you'll receive one of these errors:

Status	Code	Cause
401	unauthorized	Missing or invalid API key
403	forbidden	Valid key but insufficient permissions

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key"
  }
}

Next steps

• Send messages -- Start sending iMessages
• Rate limits -- Understand request limits
• Error codes -- Complete error reference