Authentication

All MAIA API endpoints require authentication using API tokens. Tokens provide secure, long-lived access to the API without requiring interactive login.

Generating an API Token

1. Log in to the MAIA dashboard
2. Navigate to Settings > API Tokens
3. Click Generate New Token
4. Copy and securely store the token immediately

Important

The token is only displayed once when generated. If you lose it, you'll need to generate a new one (which revokes the old token).

Using the Token

Include the API token in the Authorization header as a Bearer token:

curl -X POST "https://api.maiacompany.io/messages" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "your-channel-id",
    "sessionId": "your-session-id",
    "content": "Hello from the API!"
  }'

Token Security

Practice	Description
Store securely	Use environment variables or a secrets manager
Never commit	Don't commit tokens to version control
Rotate regularly	Generate new tokens periodically
Revoke if compromised	Immediately revoke tokens if exposed

Token Management

Check Token Status

View your token status in Settings > API Tokens to see:

• Whether an active token exists
• When it was created
• When it was last used

Revoke a Token

If your token is compromised or no longer needed:

1. Go to Settings > API Tokens
2. Click Revoke Token
3. The token is immediately invalidated

TIP

Generating a new token automatically revokes any existing token.

Error Responses

Status	Error	Description
401	Unauthorized	Missing or invalid token
401	Token revoked	Token has been revoked
403	Forbidden	Token doesn't have access to this resource

Example Error Response

{
  "error": "Unauthorized",
  "message": "Invalid or missing API token"
}

Rate Limits

API requests are rate limited per account:

Window	Default Limit
Per minute	120 requests
Per hour	3,000 requests

Successful responses include rate limit headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1704067260

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Remaining requests in current window
X-RateLimit-Reset	Unix timestamp when the window resets

When rate limited, you'll receive a 403 Forbidden response. Wait and retry with exponential backoff.

TIP

Contact your administrator to adjust rate limits for your account.