Skip to content

authentication.md

Latest commit

 

History

History
137 lines (99 loc) · 2.96 KB

authentication.md

File metadata and controls

137 lines (99 loc) · 2.96 KB

Authentication

All requests to the Texting Blue API require authentication via an API key passed in the x-api-key header.

Base URL:

https://api.texting.blue/v1

API Keys

API keys follow the format:

tb_{environment}_{32_random_chars}
Prefix Environment Description
tb_live_ Production Sends real iMessages. Use in production apps.
tb_test_ Sandbox No messages are delivered. Use during development.

Example key:

tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Key Permissions

Each API key is scoped to one or more 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
* All permissions

Creating API Keys

  1. Log in to the Texting Blue dashboard.
  2. Navigate to Settings > API Keys.
  3. Click Create API Key.
  4. Select the permissions you need and give the key a descriptive label.
  5. Copy the key immediately -- it is shown only once.

Revoking API Keys

  1. Go to Settings > API Keys in the dashboard.
  2. Find the key you want to revoke.
  3. Click Revoke and confirm.

Revoked keys are rejected immediately. Any in-flight requests using the revoked key will fail with a 401 error.

Making Authenticated Requests

Include your API key in the x-api-key header on every request.

cURL

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

Node.js

const response = await fetch("https://api.texting.blue/v1/messages", {
  headers: {
    "x-api-key": "tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  },
});

const data = await response.json();

Python

import requests

response = requests.get(
    "https://api.texting.blue/v1/messages",
    headers={"x-api-key": "tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"},
)

data = response.json()

PHP

$ch = curl_init("https://api.texting.blue/v1/messages");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

Error Responses

HTTP Status Code Description
401 unauthorized The API key is missing, invalid, or has been revoked.
403 forbidden The API key does not have the required permission for this endpoint.

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

403 Forbidden

{
  "error": {
    "code": "forbidden",
    "message": "Your API key does not have the 'messages:send' permission."
  }
}