API keys
Create, use, scope and revoke OrkStage API keys for CI/CD, scripts and the ork CLI. Token format, roles, the ten scopes, expiry, auditing and storage.
API keys authenticate automation: CI pipelines, scripts and the ork CLI. Each key acts with a
role, and its scopes narrow what that role allows. A key can never do more than its role,
and no key can manage other keys.
Token format
ork_<env>_<prefix>_<secret>
ork_live_7f3a9c21_q3Xv… (43 URL-safe characters of secret)envisliveortest. It is a label for you, and both kinds work the same way.- The prefix (
ork_<env>_plus 8 hex characters, for exampleork_live_7f3a9c21) is stored and appears in key lists and audit entries. - The server stores only the SHA-256 hash of the full token. You see the token once, when you create the key.
Creating a key
Open Integrations, then API keys, then New API key. Pick a preset or choose the scopes yourself:
| Preset | Scopes |
|---|---|
| Read only | instances:read, templates:read |
| CI/CD deploy | instances:read, instances:deploy, templates:read |
| ork CLI (developer) | instances:read, instances:deploy, templates:read, templates:write, imports:write |
| Image publishing | applications:write |
Copy the token right away and put it in your CI secret store.
Roles
| Key | tenantId | Allowed roles | Who can create it |
|---|---|---|---|
| Tenant key | required | CustomerAdmin, CustomerDeveloper, CustomerViewer | Owners and admins of that tenant, platform owners and admins |
| Organization key | omitted | PlatformAdmin, PlatformOperator | Platform owners and admins only |
The API rejects any other combination with INVALID_KEY_ROLE, TENANT_REQUIRED or
ROLE_TOO_HIGH.
Templates and catalog applications need an organization key
Templates and catalog applications are shared by all tenants, so only platform roles can change
them. Creating or publishing a template (ork template push, or a template from an import) and
registering or publishing application images need an organization key with the PlatformAdmin
role. A tenant key can still validate templates, create imports and deploy.
Scopes
| Scope | Grants (within the role) |
|---|---|
instances:read | Instances, deployments and their events, logs, metrics, tenants, cloud targets, incidents, status pages |
instances:write | Create and update instances, upgrade the template version |
instances:deploy | Deploy, destroy, approve, cancel, retry; simulation controls |
templates:read | Templates and applications; template validation |
templates:write | Create templates and versions, publish, clone; create a template from an import |
applications:write | Register applications and publish image versions (CI intake) |
incidents:write | Create incidents and post updates |
imports:write | Create and read IaC imports |
webhooks:manage | Manage webhook endpoints, send tests, list deliveries, redeliver |
audit:read | Read the audit log (and export it, with an Enterprise license) |
When a key lacks the scope an endpoint requires, the API answers 403 API_KEY_SCOPE and names the
required scope in details. An endpoint that declares no scope answers 403 API_KEY_NOT_ALLOWED.
Using a key
export ORK_TOKEN=ork_live_7f3a9c21_…
curl -s "$ORK_API_URL/api/v1/instances" -H "Authorization: Bearer $ORK_TOKEN"Requests with a bearer token need no x-orkstage-csrf header.
Lifecycle
- Expiry:
expiresAtis optional and must be in the future. An expired key gets401 INVALID_API_KEY. - Revocation: call
DELETE /api/v1/api-keys/:id(it returns204) or use the console. The key stops working at once and also gets401 INVALID_API_KEY. - Last use: the API updates
lastUsedAtand the client address at most once a minute. - Audit: every action a key takes is recorded with
actorType = API_KEYandactorLabel = "<key name> (<prefix>)".
Good practice
- Create one key per pipeline or integration, with the smallest preset that works.
- Prefer tenant keys with
CustomerDeveloperover organization keys where the job allows it. - Set an expiry. To rotate, create the new key first and then revoke the old one.
REST API overview
How the OrkStage Control API v1 works. Base path, API keys and sessions, the CSRF header, errors, pagination, correlation ids, idempotency and rate limits.
Webhooks
Receive signed OrkStage events over HTTPS. Event types, payload, signature checks in Node.js, Python and Go, retries, testing and redelivery.