velgent.

#Setting up API keys

Every call to the Velgent AI Engine is authenticated with an API key. Keys are self-service from the admin console — sign in, generate, copy the plaintext once, and paste it into your application.

This page covers minting a new key, rotating, and revoking. For the header format and error responses, see Authentication.

#Prerequisites

You need to be signed in to admin.velgent.com as either:

  • org_admin — the role assigned when you accept an invitation to a tenant. Manages your own tenant's keys.
  • root — Velgent platform staff. Manages every tenant's keys; pick the target tenant from the sidebar org picker first.

If you haven't received an invitation yet, ask whoever provisioned your organisation — see the Admin console overview for the role model.

#Mint a key

  1. Sign in to admin.velgent.com.
  2. Click API keys in the left sidebar.
  3. Type a descriptive name in the input — e.g. production, ci-runner, staging-batch. The name shows up in audit logs so you can tell at a glance which key authenticated which call.
  4. Click Generate key.

The plaintext key appears in a one-time reveal banner above the form:

velgent_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                                    [Copy]
Copy it now or rotate

This is the only time the full key is shown. After you navigate away it cannot be recovered — only the 8-character prefix (velgent_live_xxxxxxxx) is stored. If you miss the copy, revoke the key and mint a new one.

Store the key the same way you store any other production secret:

  • A secrets manager (1Password, Doppler, AWS Secrets Manager, etc.).
  • An environment variable read by your application at start.
  • Never in source control. Never in a chat message.

#Use the key

Pass it as a Bearer token on the Authorization header:

Full details on headers, errors, and idempotency on the Authentication page.

#Rotate a key

Rotation is one click with a built-in grace window, so you swap keys with zero downtime:

  1. On the key's row, click Rotate. Confirm the prompt.
  2. A new key is generated and shown once in the reveal banner — copy it (same one-time rule as minting).
  3. The old key keeps working for a grace window — 7 days by default. On its row it now shows an expiring badge and an Expires date. This is the cutover window.
  4. Deploy the new key wherever your application reads it from (env var, secret manager). Confirm the cutover in Activity logs: the new key's prefix starts appearing on requests, and the old key's Last used stops advancing.
  5. Let the old key expire automatically at the deadline, or click Revoke now on its row to close the window early once you've confirmed nothing uses it.

After expiry (or revoke), a request with the old key returns 401.

Expiry only comes from rotation

Keys you mint normally have no expiry — they show — under Expires and stay valid until you rotate or revoke them. Only a rotated-out key gets an expiry date; we never auto-expire your live keys out from under you.

Multiple keys per tenant

You can have as many active keys as you want. Use distinct keys for distinct workloads — production, batch jobs, CI runners — so rotating or revoking one doesn't affect the others.

#Revoke a leaked key

If a key ends up somewhere it shouldn't (a screenshot, a public repository, a customer's logs):

  1. Sign in to admin.velgent.com immediately.
  2. API keys → find the row with the matching prefix (the 8 chars after velgent_live_) → Revoke.
  3. Mint a replacement and deploy.

We don't revoke on your behalf today — you have full self-service control. If you've lost access to the admin console at the same time, email us and we'll revoke from our side.

#What a key sees

A key inherits the full surface of the public API (/api/v1/*) for its tenant. There is no per-key permission slicing today — every key is full-access. If you want scoped keys (read-only, or scoped to a single operation), let us know.

A key does not grant access to:

  • Other tenants' data (the engine enforces this on every call).
  • The admin console (admin auth is WorkOS sign-in with MFA, not API key).
  • The admin API at /api/admin/* (separate auth path).

#Audit + activity

Every call made with a key shows up in Activity logs in the admin console. Each row shows the operation, the API key that authenticated it (name + prefix), the provider/model that served it, latency, and any error — so you can audit per-key usage, confirm a rotation cutover, and spot a misbehaving deployment.