Authentication

The Litmus API supports two authentication methods: Bearer tokens (JWT) and API keys.

Register a New Account

curl -X POST https://api.litmus.science/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-secure-password",
    "name": "Your Name",
    "organization": "Your Organization"
  }'

Response:

{
  "id": "usr_abc123",
  "email": "user@example.com",
  "name": "Your Name",
  "organization": "Your Organization",
  "role": "requester",
  "rate_limit_tier": "standard",
  "created_at": "2026-01-27T10:00:00Z",
  "api_key": "lk_abc123def456..."
}

⚠️

Store your API key securely! It's only returned once at registration. If you lose it, you'll need to generate a new one.

Get Access Token

Exchange credentials for a JWT token:

curl -X POST https://api.litmus.science/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-secure-password"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Tokens expire after 24 hours.

Using Bearer Tokens

Include the token in the Authorization header:

curl https://api.litmus.science/experiments \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Using API Keys

Include the API key in the X-API-Key header:

curl https://api.litmus.science/experiments \
  -H "X-API-Key: lk_abc123def456..."

API keys don't expire but can be revoked.

When to Use Which

Method	Best For
Bearer Token	Interactive sessions, web apps
API Key	Server-to-server, automated pipelines

Security Best Practices

Never expose credentials in client-side code — Use server-side proxies
Rotate API keys periodically — Generate new keys and deprecate old ones
Use environment variables — Never hardcode credentials
Monitor usage — Check rate limit headers for unusual activity

Rate Limit Tiers

Tier	Requests/Minute	Requests/Day	How to Get
Standard	100	1,000	Default for new accounts
Pro	1,000	10,000	Contact sales
AI Agent	500	5,000	For automated pipelines

Contact support@litmus.science to upgrade your tier.

Overview Experiments