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.
Anyone with your key can call the API as your organisation, including consuming usage credits. Store keys in environment variables or a secret manager — never commit them to source control. If a key is leaked, email us immediately and we'll revoke it.
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": "…" }'
Common headers
| Header | Required | Description |
| --- | --- | --- |
| Authorization | Yes | Bearer velgent_live_…. |
| Content-Type | Yes for POST/PUT/PATCH | Always application/json. |
| Idempotency-Key | No | Any opaque string ≤ 128 chars. Repeated calls within 24h return the original response. |
| X-Request-Id | No | A client-generated request ID, echoed back on the response. Useful for tracing. |
Errors
| Status | Code | Meaning |
| --- | --- | --- |
| 401 | unauthorized | Missing, malformed, or revoked key. |
| 403 | forbidden | Key is valid but doesn't have access to the requested operation or org. |
| 429 | rate_limited | Per-key rate limit exceeded — see Rate limits. |
See Errors for the full list and the response shape.
Rotating keys
To rotate, email us — we'll issue a new key,
let you deploy it, then revoke the old one. There is no grace period on
revocation: once a key is revoked, the next request with it returns
401.
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.