Authentication

Xantly uses Bearer tokens for all API requests. Two token types are supported.

Token Types

Type	Format	Use case
API Key	`sk-...`	Server-to-server integrations, scripts, CI/CD.
JWT	`eyJ...`	Dashboard sessions, browser-based flows (auto-issued on login).

Both types are passed identically:

Authorization: Bearer <token>

Using Your API Key

1. Get a key

Create an API key from the Xantly Dashboard or via the Management API.

2. Store it securely

Set it as an environment variable. Never commit API keys to source control.

export XANTLY_API_KEY="sk-your-key-here"

3. Pass it in every request

Include the API key in the Authorization: Bearer header with every request.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XANTLY_API_KEY"],
    base_url="https://api.xantly.com/v1",
)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XANTLY_API_KEY,
  baseURL: "https://api.xantly.com/v1",
});

curl -sS https://api.xantly.com/v1/chat/completions \
  -H "Authorization: Bearer $XANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello"}]}'

Authentication Errors

HTTP	`error.code`	Meaning	Fix
`401`	`invalid_api_key`	Token is missing, malformed, or revoked.	Verify the `Authorization` header contains a valid `sk-...` key.
`401`	`expired_token`	JWT has expired.	Re-authenticate to obtain a fresh JWT.
`403`	`insufficient_permissions`	Key doesn't have the required scope.	Check key permissions in the dashboard.

Security Best Practices

Environment variables only. Store keys in XANTLY_API_KEY, never in source code or client bundles.
Rotate regularly. Create a new key, migrate, then revoke the old one.
Least privilege. Assign only the scopes each key actually needs.
Monitor usage. Use the dashboard to track per-key request volume and cost.
Never expose in browsers. API keys are server-side only. Browser apps should use JWT-based auth via your backend.

Rate Limits

Rate limits are applied per API key and per organization. When exceeded, the API returns 429 with a Retry-After header.

{
  "error": {
    "message": "Rate limit exceeded. Retry after 2 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Implement exponential backoff with jitter for production resilience.

On this page