Getting StartedAuthentication

Authentication

All requests to the ChumiAI API must be authenticated using your API key. This guide covers how to include your key in requests and handle authentication errors.

Using Your API Key

Include your API key in the X-API-Key HTTP header with every request.

Example Authenticated Request
curl -X GET "https://api.chumiai.app/api/v1/whatsapp/templates" \
   -H "X-API-Key: YOUR_API_KEY" \
   -H "Content-Type: application/json"

The API key must be sent as a header, not as a query parameter or in the request body. This ensures the key doesn't get logged in URLs or cached by intermediaries.

Authentication in Different Languages

Here's how to include the API key in common frameworks and languages:

Node.js (fetch)
const response = await fetch("https://api.chumiai.app/api/v1/whatsapp/templates", {
method: "GET",
headers: {
  "X-API-Key": process.env.CHUMIAI_API_KEY,
  "Content-Type": "application/json",
},
});

const data = await response.json();
Python (requests)
import requests
import os

response = requests.get(
  "https://api.chumiai.app/api/v1/whatsapp/templates",
  headers={
      "X-API-Key": os.environ["CHUMIAI_API_KEY"],
      "Content-Type": "application/json",
  }
)

data = response.json()
PHP (cURL)
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.chumiai.app/api/v1/whatsapp/templates");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: " . getenv("CHUMIAI_API_KEY"),
  "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Error Responses

If authentication fails, the API will return one of these error responses:

401 Unauthorized

Returned when no API key is provided or the key is invalid.

401 Response
{
"error": "Unauthorized",
"message": "Missing or invalid API key. Provide a valid key in the X-API-Key header.",
"statusCode": 401
}

403 Forbidden

Returned when your API key is valid but doesn't have the required scope for the requested action.

403 Response
{
"error": "Forbidden",
"message": "Your API key does not have the required scope: whatsapp:send",
"statusCode": 403
}

429 Too Many Requests

Returned when you've exceeded the rate limit for your plan.

429 Response
{
"error": "Too Many Requests",
"message": "Rate limit exceeded. Please retry after 60 seconds.",
"statusCode": 429,
"retryAfter": 60
}

Base URL & Headers

All API requests use the following base URL and standard headers:

| Header | Value | Required | | :--- | :--- | :--- | | X-API-Key | Your API key | Yes | | Content-Type | application/json | Yes (for JSON bodies) | | Accept | application/json | Recommended |

Base URL:

Base URL
https://api.chumiai.app

All endpoints are relative to this base URL. For example, sending a template message would be:

POST https://api.chumiai.app/api/v1/whatsapp/send-template

Need an API Key?

If you haven't created an API key yet, follow the API Keys Setup guide to generate one.

Next Steps