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/ApiKeyson 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— requiredpassword— requireddeviceId— 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 requestsexpires_in— seconds until the access token expiresrefresh_token— use this to get a new access token without signing in againmust_change_password—truewhen 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 |