Authentication and API keys
Create, scope, and use Ethen Gateway API keys for programmatic access.
All Gateway API requests require authentication with an Ethen API key sent as a Bearer token.
Sending the API key
Include the key in the Authorization header:
Authorization: Bearer ***If the header is missing, the Gateway returns a 401 error with code missing_api_key. If the key is invalid, revoked, or expired, it returns 401 with code invalid_api_key, revoked_api_key, or expired_api_key.
Key scopes
Each API key is assigned one or more scopes that control what operations it can perform:
| Scope | Description |
|---|---|
gateway:invoke | Create chat completions and manage streams. |
gateway:read | View request logs, usage summaries, and stream state. |
A key without the gateway:invoke scope receives a 403 error with code insufficient_scope when making chat completion requests.
Creating a key
Keys are created in the API Keys dashboard within the Gateway product. The raw key is displayed only once at creation time. The Gateway stores only a one-way hash of the key, along with its prefix and suffix for identification.
Key lifecycle
- Active — the key works for all scoped operations.
- Expired — keys can be assigned an expiration date. Expired keys return
expired_api_key.
- Revoked — keys can be revoked at any time. Revoked keys return
revoked_api_key.
Environment and project isolation
Every key is bound to a single project and environment (live or test). Cross-project access is rejected with a 403 error.
Best practices
- Store the key in an environment variable (e.g.
ETHEN_GATEWAY_KEY). - Never commit the raw key to source control.
- Use separate keys for development and production environments.
- Rotate keys periodically using the API Keys dashboard.