Skip to content

Authentication

Every OnVeris API request must include valid credentials, so that the Gateway knows who is calling and what they may do. Two methods are supported: API Keys, for integrations, and access tokens, for applications where people sign in with their own OnVeris account.

Note

Earlier versions of OnVeris accepted API requests without credentials while no API Keys existed. That is no longer the case.

API Keys

API Keys are the recommended method for programmatic access. They do not expire unless given an expiry date, and need no sign-in.

Getting A Key

There are two kinds of key:

  • User Keys act as one person, and can do whatever that person can. Anyone with access to the Gateway's administration pages can create their own, at /Account/ApiKeys on the Gateway.
  • Service Keys belong to no person, and can only do what an administrator grants them.

See API Keys for how to create and manage them.

Using A Key

Send the key in any of these headers:

Authorization: Bearer <your-api-key>
Authorization: ApiKey <your-api-key>
X-API-Key: <your-api-key>

Authorization: Bearer is what the OpenAI libraries send.

Example using curl:

curl https://onveris.yourcompany.com/v1/chat/completions \
  -H "Authorization: Bearer onveris_sk_…" \
  -H "Content-Type: application/json" \
  -d '{"model":"assistant:hr-helper","messages":[{"role":"user","content":"Hello"}]}'

Keys start onveris_sk_ for a Service Key and onveris_uk_ for a User Key. Keys created before OnVeris was renamed start optima_sk_ or optima_uk_, and they keep working.

An administrator can also limit a key to certain IP addresses, and to a number of requests per second, minute or hour. See Errors and Limits.

Scopes

A scope is one area of the API. Each endpoint needs a scope:

Scope Allows
chat.completions /v1/chat/completions
responses /v1/responses
embeddings /v1/embeddings
models.read /v1/models and /onveris/v1/models
knowledge.read, knowledge.write, knowledge.admin The Knowledge Base API
conversations.read, conversations.write Conversations
documents.read, documents.write Uploaded documents
assistants.read, assistants.write, assistants.admin The Assistants API
tools.read The tool list
nodes.read Node status

A User Key holds the scopes that match its user's permissions — the Chat permission alone gives chat, responses, embeddings, models, conversations, documents and tools. A Service Key holds exactly the scopes it was given.

A request needing a scope the key does not hold will be refused with 403:

{
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This service key does not hold chat.completions. Service keys carry only the scopes granted to them explicitly — add it in Settings → API Keys.",
  "required_scopes": ["chat.completions"],
  "held_scopes": ["embeddings", "models.read"]
}

Access Tokens

Access tokens suit applications where people sign in with their own OnVeris username and password. Requests made with a token act as that person. Tokens are short-lived and must be refreshed.

Signing In

Request:

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

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

  • username — required
  • password — required
  • deviceId — optional. Identifies the calling device or application.

Response:

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

  • access_token — include this in API requests
  • expires_in — seconds until the access token expires
  • refresh_token — use this to get a new access token without signing in again
  • must_change_password — true when the person signed in with a temporary password. See Changing a password

Wrong credentials will return 401 with no body. An expired temporary password will return 401 with {"error": "temp_password_expired"}.

Using A Token

Send the access token in the Authorization header:

Authorization: Bearer <access_token>

Refreshing A Token

When the access token expires, use the refresh token to get a new one:

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 tokens will be replaced on each refresh. Use the new refresh token next time. A refresh token lasts 14 days unless used.

Changing A Password

When must_change_password is true, every request except changing the password, refreshing and signing out will be refused with 403:

{ "error": "password_change_required", "message": "…" }

To set a new password:

Request:

POST /api/auth/change-password
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "currentPassword": "the-temporary-password",
  "newPassword": "a-new-password"
}

The new password must be at least 8 characters. The response will contain fresh tokens, in the same shape as signing in. A password that is refused will return 400 with {"errors": [...]}.

Signing Out

Send the refresh token to end the session:

Request:

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

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

This returns 200 OK, and the refresh token will be revoked.

Choosing Between API Keys And Access Tokens

Scenario Recommended method
Server-to-server integration Service Key
Automation scripts and pipelines Service Key
A person's own scripts User Key
Applications where people sign in Access token