Authentication

OptimaGPT API requests must include valid credentials. Two authentication methods are supported: JWT bearer tokens (for user accounts) and API keys (for integrations).

API keys

API keys are the recommended method for programmatic access. They are long-lived and do not require a login flow.

Creating an API key

API keys are created by an administrator in the Gateway's Configuration page under the API Keys tab. Each key can be scoped to specific permissions. Ask your administrator to create a key for your integration.

Using an API key

Include the key in the Authorization header of every request:

Authorization: ApiKey <your-api-key>

Alternatively, you can use the X-API-Key header:

X-API-Key: <your-api-key>

Example using curl:

curl https://optima.yourcompany.com/v1/chat/completions \
  -H "Authorization: ApiKey sk-optima-abc123" \
  -H "Content-Type: application/json" \
  -d '{"model":"llama-3.1-8b","messages":[{"role":"user","content":"Hello"}]}'

JWT bearer tokens

JWT tokens are suitable when building applications where users authenticate with their own OptimaGPT credentials. Tokens are short-lived and must be refreshed periodically.

Obtaining a token

Request:

POST /api/auth/login
Content-Type: application/json

{
  "username": "alice",
  "password": "password123",
  "deviceId": "my-app-v1"
}

• username — required
• password — required
• deviceId — optional. An arbitrary string identifying the calling device or application. Useful for auditing active sessions.

Response:

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBp..."
}

• access_token — include this in API requests
• expires_in — seconds until the access token expires
• refresh_token — use this to obtain a new access token without re-entering credentials

Using a bearer token

Include the access token in the Authorization header:

Authorization: Bearer <access_token>

Refreshing a token

When the access token expires, use the refresh token to obtain a new one without re-authenticating:

Request:

POST /api/auth/refresh
Content-Type: application/json

{
  "refresh_token": "dGhpcyBp..."
}

Response:

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "bmV3cmVm..."
}

Both the access token and refresh token are rotated on each refresh.

Signing out

To invalidate the current session, send the refresh token in the request body:

Request:

POST /api/auth/logout
Content-Type: application/json

{
  "refresh_token": "dGhpcyBp..."
}

Returns 200 OK on success. The refresh token is revoked and any session cookies are cleared.

Choosing between API keys and JWT tokens

Scenario	Recommended method
Server-to-server integration	API key
Automation scripts and pipelines	API key
Applications where end users authenticate	JWT bearer token
Development and testing	Either

JWT tokens tie requests to a specific user account and its permissions. API keys have their own permission set configured by the administrator. Both methods enforce the same permission checks on protected endpoints.