#Authentication

The Velgent AI Engine authenticates every request with an API key sent in the Authorization header. Each key is scoped to a single organisation; all data, usage, and billing roll up to that organisation.

#API keys

Keys look like:

velgent_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The 8-character prefix (velgent_live_xxxxxxxx) is safe to log for identification — the full secret is only shown once at creation time, so store it somewhere you can retrieve it later.

Mint, rotate, and revoke keys self-service from the admin console: Setting up API keys walks through the full flow with screenshots-worth of detail.

#Sending the key

Pass the key as a Bearer token on every request:

Authorization: Bearer velgent_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type:  application/json

A full example:

curl https://aiengine.velgent.com/api/v1/summarise \
  -H "Authorization: Bearer $VELGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "…" }'

#OAuth 2.0 (client credentials)

For a stronger posture, use the OAuth2 client credentials flow instead of sending a static key on every request. You exchange a long-lived client_id + client_secret for a short-lived access token (1 hour), and send that on your API calls. The benefit: the credential that travels on every request — the one that lands in logs or passes through a proxy — expires in an hour, so a leak there has a small blast radius.

1. Create an OAuth client in the admin console (admin.velgent.com → OAuth clients). Copy the client_id and the one-time client_secret.

2. Exchange them for an access token:

curl https://aiengine.velgent.com/api/v1/oauth/token \
  -u "$VELGENT_CLIENT_ID:$VELGENT_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "token_type":   "Bearer",
  "expires_in":   3600,
  "scope":        ""
}

(Credentials may also be passed as form fields client_id / client_secret instead of HTTP Basic.)

3. Call the API with the access token — same Authorization: Bearer header, just the token instead of the static key:

curl https://aiengine.velgent.com/api/v1/summarise \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "…" }'

When the token expires (after expires_in seconds), request a new one with the same client credentials — there are no refresh tokens in the client_credentials flow. Rotating or revoking the OAuth client stops new tokens from being issued immediately; tokens already minted stay valid until they expire (≤ 1 hour).

#Common headers

#Errors

See Errors for the full list and the response shape.

#Rotating keys

One-click, zero-downtime, self-service from admin.velgent.com → API keys. Click Rotate on a key and Velgent:

1. Mints a replacement and shows its plaintext once — copy it.
2. Keeps the old key working for a grace window (7 days by default), so your integrations cut over with no outage. During the window the old key shows an expiring badge and an Expires date.
3. Expires the old key automatically at the deadline — after that, a request with it returns 401.

Your job during the window: deploy the new key wherever your app reads it, then confirm the cutover in Activity logs (the new key's prefix starts appearing; the old key's "last used" goes stale). You can let the old key expire on its own, or click Revoke now to close the window early.

Keys you mint normally have no expiry (they show — under Expires) — they stay valid until you rotate or revoke them. Only a rotated-out key carries an expiry.

See Setting up API keys for the full flow and the leaked-key playbook.

#Organisations

A key belongs to exactly one organisation. Multiple keys per organisation are supported and recommended — use distinct keys for distinct workloads (e.g. production vs. batch jobs) so you can rotate or revoke one without affecting the other.