# Gateway API authentication guide

Secure your Gateway API integration with proper authentication and scopes.

- Date: Sep 20, 2025
- Reading time: 14 min
- Level: Beginner
- Tags: Gateway, Auth, Security

## Takeaways
- Use client credentials flow for server-to-server authentication.
- Implement proper key rotation and scope management.
- Handle rate limits and error responses gracefully.

## 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.

```bash
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.