Skip to main content

API keys

A personal API key lets your code call the Model Gateway. Keys start with vcpk_, belong to the person who created them, and never carry the admin role.

These endpoints need a Keycloak access token. An API key cannot be used to list, create or revoke keys, including itself.

Create a key​

POST/api-keys

Creates a key that belongs to you and returns it. This is the only time the full key is returned. Orchestrate stores only its hash.

Body​

namestringoptional
A label, such as the application that will use it.

Response fields​

idstringoptional
The key's id, for revoking it.
namestring or nulloptional
The label.
prefixstringoptional
The first characters of the key, to recognise it later.
created_atstringoptional
When it was created.
keystringoptional
The key. Store it now.

Responses​

201
Created.
401
No valid Keycloak access token.

List your keys​

GET/api-keys

Your own keys, newest first, with id, name, prefix, created_at and revoked_at. The key itself is never returned.

Revoke a key​

DELETE/api-keys/{key_id}

Revokes a key. It stops working on the next request. The key's record is kept, with the time it was revoked. You can revoke your own keys. A platform admin can revoke anyone's.

Responses​

200
Revoked. Returns id and revoked_at.
403
The key is not yours.
404
No such key.

Rotate a key​

POST /api-keys/{key_id}/rotate with {"overlap_hours": 24} (0 to 720) gives your key a new secret, returned once, and keeps its id, name, limits and scopes. The old secret works until the overlap ends. See Usage, limits and prices.

Project keys for the Agent API are on the Agent API page, and agent keys on A2A and agent keys.

Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →