Authentication

All API requests require authentication via a Bearer token in the Authorization header.

Authentication Methods

Method	Use Case	Lifetime
API Token	Server-to-server integrations, scripts, CI/CD	Long-lived (until revoked)
Session Token	Browser-based applications	Short-lived (auto-refreshes)

For programmatic access, API tokens are recommended. See API Tokens for setup instructions.

Using Bearer Tokens

Include your token in the Authorization header:

Authenticate a request

curl https://api.catalyzed.ai/me \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const response = await fetch("https://api.catalyzed.ai/me", {
  headers: {
    Authorization: `Bearer ${apiToken}`,
  },
});
const user = await response.json();

import requests

response = requests.get(
    "https://api.catalyzed.ai/me",
    headers={"Authorization": f"Bearer {api_token}"}
)
user = response.json()

Token Scopes

API tokens are scoped to a specific team. When you create a token, you select which team it belongs to. The token can only access resources within that team.

To work with multiple teams, create separate API tokens for each team.

Error Responses

401 Unauthorized

Returned when the token is missing, invalid, or expired.

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or expired token"
}

403 Forbidden

Returned when the token is valid but lacks permission for the requested resource.

{
  "error": "FORBIDDEN",
  "message": "Insufficient permissions for this resource"
}

Session Authentication (Browser Apps)

For browser-based applications, users authenticate via email/password or magic link. Session tokens are:

Managed automatically via HTTP-only cookies
Short-lived with automatic refresh
Tied to a specific browser session

Login with email/password

curl -X POST https://api.catalyzed.ai/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

const response = await fetch("https://api.catalyzed.ai/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  credentials: "include", // Include cookies
  body: JSON.stringify({
    email: "[email protected]",
    password: "your-password",
  }),
});

import requests

session = requests.Session()
response = session.post(
    "https://api.catalyzed.ai/auth/login",
    json={
        "email": "[email protected]",
        "password": "your-password"
    }
)
# Session cookies are automatically stored

Security Best Practices

Never expose tokens in client-side code - Use environment variables or secrets management
Rotate tokens periodically - Create new tokens and revoke old ones
Use minimal scope - Create tokens only for the teams that need access
Revoke compromised tokens immediately - Via Settings > API Tokens in the app