Authentication

Every request carries a Bearer token in the Authorization header. There are two kinds of token.

Authorization: Bearer <token>

Admin credential

A single administrative credential authorises provisioning operations — creating projects and managing their API keys. It is held by the operator, never by a partner.

Uses the admin credential
`POST /v1/projects`
`POST /v1/projects/{id}/keys`
`GET /v1/projects/{id}/keys`
`DELETE /v1/keys/{id}`

If the admin credential is not configured, the provisioning endpoints are closed, not open — the service fails safe.

Project API keys

Each project has one or more API keys, returned in full once at creation and never again. A partner uses their project key for all day-to-day calls.

Uses a project API key
`POST /v1/projects/{id}/documents`
`GET /v1/jobs/{id}`
`POST /v1/documents/{id}/retry` · `DELETE /v1/documents/{id}`
`POST /v1/search` · `POST /v1/answer` · `POST /v1/answer/stream`

Keys are revocable and can be given an expiry, so a leaked or rotated key can be retired without deleting anything. Only a hash and a short display prefix are stored server-side.

Key lifecycle

# issue an additional key that expires in 90 days (admin)
curl -X POST https://api.your-host/v1/projects/$PROJECT_ID/keys \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-pipeline", "expires_in_days": 90}'

# revoke a key by id (admin, idempotent)
curl -X DELETE https://api.your-host/v1/keys/$KEY_ID \
  -H "Authorization: Bearer $ADMIN_API_KEY"

Always send credentials over TLS, and never disable certificate verification.

← PreviousOntologies Next →Projects