Authentication

API Key Format#

All API requests require a key in the Authorization header:

Authorization: Bearer ck_live_aB3kLm9xPqR7wZ2nYhJ4cD6fG8tV0sE

Keys follow the format ck_live_ + 32 alphanumeric characters. They are SHA-256 hashed before storage — Chamelingo never stores your raw key.

Scopes#

Each API key is granted one or more scopes that control endpoint access:

By default, keys are created with ["tutor"]. Request only the scopes your integration needs — principle of least privilege.

curl -X POST https://api.chamelingo.com/api/v1/keys \
  -H "Cookie: better-auth.session_token=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name": "Study Bot", "scopes": ["tutor", "decks", "progress"]}'

import requests

response = requests.post(
    "https://api.chamelingo.com/api/v1/keys",
    headers={"Cookie": "better-auth.session_token=YOUR_SESSION"},
    json={
        "name": "Study Bot",
        "scopes": ["tutor", "decks", "progress"],
    },
)
key = response.json()["key"]  # Save this immediately

const response = await fetch("https://api.chamelingo.com/api/v1/keys", {
  method: "POST",
  headers: {
    Cookie: "better-auth.session_token=YOUR_SESSION",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Study Bot",
    scopes: ["tutor", "decks", "progress"],
  }),
});
const { key } = await response.json(); // Save this immediately

Key Limits#

• Maximum 5 active keys per user account
• Keys can be revoked (soft delete) but not un-revoked
• The full key is shown only at creation time
• Revoked keys immediately stop working

Quotas#

API requests consume your Chamelingo subscription quota. Usage is shared between the web app and the API:

Check your current usage anytime:

curl https://api.chamelingo.com/api/v1/usage \
  -H "Authorization: Bearer ck_live_YOUR_KEY_HERE"

Errors#

Missing or invalid keys return 401:

{
  "success": false,
  "error": {
    "title": "Sign in required",
    "message": "Invalid or expired API key.",
    "retryable": false,
    "statusCode": 401,
    "code": "UNAUTHENTICATED"
  }
}

Accessing an endpoint without the required scope returns 403:

{
  "success": false,
  "error": {
    "title": "Access denied",
    "message": "This API key does not have the \"decks\" scope.",
    "retryable": false,
    "statusCode": 403,
    "code": "FORBIDDEN"
  }
}