orkiva Authenticate and select context#
Use the Orkiva installation’s API prefix, normally /api/v1, and include its configured base subpath if present. Keys created in Settings → API Keys use the complete orkiva-prefixed token directly as the Authorization value. Bearer orkivasa_… is a separate Orkiva service-account credential format; these formats are not interchangeable. Browser sessions use the application’s cookie/refresh flow. Do not copy browser cookies into long-lived automation.
curl --fail-with-body \
-H "Authorization: $ORKIVA_API_KEY" \
-H "x-cluster-name: staging" \
"$ORKIVA_URL/api/v1/pods/default"The cluster name is an example. Use your exact configured name, encoding it as the client expects when it contains non-ASCII characters. The API also registers the explicit /api/v1/_clusters/:cluster route family. Delivery targets carry their own destination configuration.
Common read routes#
| Route | Use |
|---|---|
| GET /api/v1/version | Application version metadata. |
| GET /api/v1/clusters | Accessible cluster connections. |
| GET /api/v1/pods/:namespace | Pods in a namespace; _all is the all-namespace list form. |
| GET /api/v1/pods/:namespace/:name | A pod detail. |
| GET /api/v1/nodes/_all/:name | A cluster-scoped node detail through the generic route convention. |
| GET /api/v1/delivery/projects | Delivery project collection. |
| GET /api/v1/delivery/runs/:id/detail | Detailed run evidence. |
Mutations and concurrency#
Use an Idempotency-Key for operations that support it. The general middleware accepts 8–128 safe characters when supplied; Delivery mutation helpers generate such keys and send record versions in If-Match for versioned updates. Reuse the same key for an uncertain retry of the same logical request, not for a different payload.
If the server reports the operation is still running, inspect or wait for its result rather than creating a second identity immediately. A version conflict means you must refresh the record and review the changed state before updating it.
Error handling#
| Condition | Client behavior |
|---|---|
| 401 | Refresh/re-establish the appropriate authentication; an expired API key is not a browser session. |
| 403 | Inspect permissions, scope and any strong-authentication requirement. |
| 409 / precondition conflict | Refresh and reconcile state; do not blindly overwrite a newer record. |
| Validation error | Correct the request using its structured error detail and field context. |
| Unavailable or unknown outcome | Retain the request/operation identifier and inspect the result before retrying a mutation. |
Delivery errors expose fields such as code, detail and requestId. Log these identifiers with sanitized context rather than secrets or complete credentials.