Skip to main content

​
Overview

API keys are how you authenticate non-interactive integrations with ORCA — CI pipelines, scheduled jobs, the CLI, the dbt integration, and any custom code calling the public API. Keys are managed through the Settings → API keys page (admin only) or via the management endpoints. Each key belongs to one organisation, has a fixed scope, and can be revoked at any time without affecting other keys. This page covers key lifecycle. For how to use a key once you have one, see API reference.

​
Key scopes

Every API key is created with one of four scopes. Scope is set at creation and cannot be changed afterward (revoke and recreate if you need to upgrade).
ScopePermissionsTypical use
read (default)Read jobs, files, results, scores, contractsDashboards, reporting integrations, SIEM ingestion
scanRead + trigger scans on existing sourcesScheduled re-scans, CI quality gates
writeRead + scan + create jobs, upload files, edit contractsData pipelines that ingest new files
adminEverything write can do + manage other keys, users, org settingsBootstrapping scripts, infrastructure-as-code
The principle is least privilege: pick the smallest scope that works for the integration. Most production integrations are read or scan. admin keys should be rare and rotated frequently.

​
Creating a key

In Settings → API keys, click Create key. You’ll be asked for:
  • Name — a human label so you remember what the key is for (e.g. “Airflow prod”, “CI quality gate”)
  • Scope — one of the four above
  • Expires at (optional) — set an absolute expiration date for time-limited keys
ORCA returns the raw key once and only once. Copy it immediately and store it in your secret manager. After you close the dialog, the raw key is gone — only the key prefix (the first few characters, used for identification in logs) remains visible. There’s a hard limit of 10 active keys per organisation. Revoke unused keys to make room.

​
Via the API

POST /api/v1/api-keys
Authorization: Bearer <admin JWT>
Content-Type: application/json

{
  "name": "Airflow prod ingestion",
  "scope": "write",
  "expires_at": "2027-04-07T00:00:00Z"
}
Response (the only time the raw key is returned): 
{
  "data": {
    "id": "8fa1...",
    "name": "Airflow prod ingestion",
    "scope": "write",
    "key": "ok_live_3f8a9d2e_a1b2c3d4e5f6...",
    "created_at": "2026-04-07T09:14:22Z"
  }
}
The first segment (ok_live_3f8a9d2e) is the key prefix — it’s safe to log, embed in dashboards, or store alongside the key id for identification.

​
Listing keys

GET /api/v1/api-keys
Returns every key for the org with name, scope, prefix, last-used timestamp, created-at, and active flag. The full key value is never returned by this endpoint — only by the create endpoint, only once. The last_used_at column is the easiest way to find dead keys to revoke.

​
Updating a key

You can change the name of a key after creation, but not its scope. To change scope, revoke and create a new key. 
PATCH /api/v1/api-keys/{key_id}
{
  "name": "Airflow prod (renamed)"
}

​
Revoking a key

DELETE /api/v1/api-keys/{key_id}
Revocation is immediate — any in-flight request authenticated with the revoked key will continue to its current response, but the next request will fail with 401 Unauthorized. Revoked keys are kept in the database (for the audit trail) but marked is_active = false. In the UI: click the Revoke button on the key row and confirm.

​
Authentication

To use a key in a request, send it in the Authorization header with the Bearer prefix: 
curl https://app.orca-klavest.app/api/v1/jobs \
  -H "Authorization: Bearer ok_live_3f8a9d2e_a1b2c3d4e5f6..."
The same header format works for both API keys and JWT access tokens — ORCA detects which is which from the prefix.

​
Rotation

API keys never auto-rotate. Best practice for production integrations:
1

Create the new key

Create a new key with the same scope and a name that includes a date or version (e.g. “Airflow prod 2026-04”).
2

Deploy alongside the old key

Update your secret manager with both keys. Verify the new key works against a non-critical endpoint.
3

Cut over

Switch the integration to the new key. Watch the audit log for api_key_used events to confirm traffic moved.
4

Revoke the old key

After 24 hours of clean traffic on the new key, revoke the old one.
Set rotation calendar reminders — quarterly is a reasonable default for write/admin scopes.

​
Audit and observability

Every key action creates an audit log entry:
  • api_key_created — when a key is issued, with name + scope + key id in metadata
  • api_key_revoked — when a key is revoked
  • api_key_used — on each authenticated API request, with the key prefix in metadata
The api_key_used events let you reconstruct exactly what an integration did from a security review perspective.

​
Limits

  • 10 active keys per organisation. Revoke unused keys to free slots.
  • Admin role required to create, list, update, or revoke keys.
  • No raw key recovery. If you lose a key, you must revoke and create a new one. ORCA stores only a hash, not the raw value.

​
Tips

  • Name keys after their consumer. “Airflow prod” beats “key 3” by a mile when you’re trying to revoke the right one in an incident.
  • Use expiration dates for time-bound work. Contractor needs API access for two weeks? Create a key with expires_at set to two weeks out and forget about it.
  • Don’t share keys between integrations. One integration per key makes blast-radius small if one leaks.
  • Monitor last_used_at. Anything not used in 60 days is a candidate for revocation.

​
What’s next?