Authentication

All gateway endpoints require authentication. Gatewyse supports two authentication methods: API keys (for programmatic access) and JWT tokens (for dashboard and SSO-based sessions).

API Key Authentication

API keys are the primary authentication method for gateway requests. Keys are prefixed with aigw_sk_ and passed via the Authorization header as a Bearer token.

curl https://your-gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer aigw_sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "Hello"}]}'

Creating API Keys

API keys are created through the admin dashboard under API Keys. When creating a key you can configure:

Field	Description
name	A human-readable name for the key (1-200 characters).
scopes.capabilities	Array of allowed capabilities (see table below). Defaults to ["chat"].
scopes.providerIds	Restrict the key to specific provider configurations. Empty array means all providers.
scopes.modelIds	Restrict the key to specific models. Empty array means all models.
rateLimits.requestsPerMinute	Per-key requests-per-minute limit.
rateLimits.requestsPerDay	Per-key requests-per-day limit.
rateLimits.tokensPerDay	Per-key tokens-per-day limit.
expiresAt	ISO 8601 datetime after which the key is automatically expired.
metadata	Arbitrary key-value metadata for your own tracking.

Capabilities

Each API key is scoped to one or more capabilities that control which endpoints it can access.

Capability	Endpoints
chat	/v1/chat/completions, /v1/messages
completions	/v1/completions
embeddings	/v1/embeddings
audio	/v1/audio/transcriptions, /v1/audio/translations
tts	/v1/audio/speech
images	/v1/images/generations
rerank	/v1/rerank
video-generation	/v1/video/generations
usage:read	/v1/usage
budget:read	/v1/budget

Key Lifecycle

API keys have the following statuses:

Status	Description
active	The key is valid and can be used for requests.
expired	The key has passed its expiresAt date. Automatically detected on use.
revoked	The key has been manually revoked via the admin dashboard or API.

JWT Authentication

JWT tokens are used by the admin dashboard and SSO-authenticated sessions. Tokens are signed with HS256 and must include:

• sub — the user ID
• tenantId — the tenant the user belongs to
• type — must be "access"
• jti — a unique token identifier (required; used for revocation)

JWTs are passed as Bearer tokens in the Authorization header, or via an HttpOnly cookie named access_token.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Tokens without a jti claim are rejected. Revoked tokens (checked against a Redis blocklist) are also rejected.

Rate Limiting

Two layers of rate limiting are applied to every request:

1. API Key rate limits — per-key limits configured when the key is created (requestsPerMinute, requestsPerDay, tokensPerDay).
2. Tenant rate limits — global limits configured at the tenant level.

Rate limiting uses a sliding-window algorithm backed by Redis sorted sets with server-side timestamps (preventing clock-skew bypass).

When a rate limit is exceeded, the gateway returns:

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": "RATE_LIMIT_EXCEEDED"
  }
}

HTTP Status: 429 Too Many Requests

Error Responses

HTTP Status	Code	Description
401	AUTH_REQUIRED	No authentication credentials provided.
401	AUTH_INVALID_TOKEN	JWT token is invalid or malformed.
401	AUTH_TOKEN_EXPIRED	JWT token has expired.
401	AUTH_INVALID_API_KEY	API key not found or invalid.
401	AUTH_API_KEY_EXPIRED	API key has passed its expiration date.
401	AUTH_API_KEY_REVOKED	API key has been revoked.
403	AUTH_FORBIDDEN	Valid credentials but insufficient permissions for the requested capability.