Authentication

All API requests require authentication using an API key.

Getting Your API Key

1. Go to converra.ai/settings
2. Click Create API Key
3. Give it a name (e.g., "Production", "Development")
4. Copy the key - it's only shown once

WARNING

Store your API key securely. Never commit it to version control or expose it client-side.

Using Your API Key

Include the API key in the Authorization header:

curl https://converra.ai/api/v1/prompts \
  -H "Authorization: Bearer sk_live_your_api_key_here"

API Key Format

Keys follow this format:

Prefix	Environment
sk_live_	Production
sk_test_	Development/Testing

SDK Authentication

import { Converra } from 'converra';

const converra = new Converra({
  apiKey: process.env.CONVERRA_API_KEY
});

MCP Authentication

claude mcp add converra https://converra.ai/api/mcp \
  --header "Authorization: Bearer sk_live_your_key"

Error Responses

Invalid API Key

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Status: 401 Unauthorized

Missing API Key

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authorization header required"
  }
}

Status: 401 Unauthorized

Expired API Key

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key has expired"
  }
}

Status: 401 Unauthorized

Revoking Keys

To revoke an API key:

1. Go to converra.ai/settings
2. Find the key in the list
3. Click Revoke

TIP

After revoking a key, any requests using it will immediately fail. Create a new key before revoking the old one if you need to rotate keys without downtime.

Best Practices

1. Use environment variables - Never hardcode keys
2. Rotate regularly - Create new keys periodically
3. Use separate keys - Different keys for dev/staging/prod
4. Minimal permissions - Use test keys for development
5. Monitor usage - Check for unexpected activity

Rate Limits

API requests are rate limited per API key:

Plan	Requests/minute
Free	60
Pro	300
Enterprise	Custom

Rate limit headers are included in responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1640000000