Authentication overview
The Gateway API uses Bearer token authentication with client ID and secret. Tokens are passed in the Authorization header.
All requests must be authenticated. Unauthenticated requests receive a 401 response.
curl https://<gateway-host>/v1/chat/completions \
-H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
-H "Content-Type: application/json" \
-d '{"input": {"text": "Hello"}}'Key management best practices
Create separate API keys for each environment (development, staging, production). Use least-privilege scopes for each key.
- Rotate keys regularly (monthly recommended).
- Never commit keys to version control.
- Use environment variables or secret managers.
- Monitor key usage for anomalies.
API scopes and permissions
API keys can be scoped to specific capabilities. Request only the scopes you need for your integration.
- chat:read - Read chat completions.
- chat:write - Create chat completions.
- audio:transcribe - Transcribe audio.
- audio:synthesize - Generate speech.
- avatar:stream - Stream avatar animations.
- finetune:manage - Create and manage fine-tuning jobs.
Rate limits and error handling
The Gateway API enforces rate limits per key. Handle 429 responses with exponential backoff.
- Check Retry-After header for backoff duration.
- Implement client-side request queuing.
- Monitor your usage against quota limits.