Skip to main content

Quick start

You want to: call OpenConsole from a terminal with an API key, before handing it to an agent.

You need curl and jq. The examples were run against a test cluster with the crashlab namespace of the code repository's hack/k3d/crashlab.yaml; your names will differ.

1. Create a key​

In OpenConsole: your name (top right) → API keys → New API key. Pick the cluster, the namespaces and the Read-only (safe) template, then copy the key (oc_ and 40 characters). It is shown once. Details: Your API keys.

export OC_URL=https://openconsole.example.com # your OpenConsole address, no trailing slash
export OPENCONSOLE_API_KEY=oc_… # the key you copied

2. Who am I​

curl -s -H "Authorization: Bearer $OPENCONSOLE_API_KEY" "$OC_URL/api/auth/me" \
| jq '{key: .apiKey.name, grants: .apiKey.grants, namespaces}'
{
"key": "claude-code",
"grants": ["deployments:get", "deployments:list", "pods:get", "pods:list", "pods:logs"],
"namespaces": ["crashlab"]
}

namespaces and permissions in the full answer are what the key reaches now (key ∩ your roles ∩ the admin's policy); start every script or agent with this call.

3. Pick the cluster​

Each request works on your selected cluster unless it names one with X-OpenConsole-Cluster, by name or id. The clusters the key can use:

curl -s -H "Authorization: Bearer $OPENCONSOLE_API_KEY" "$OC_URL/api/clusters/public"
{"items":[{"id":1,"name":"k3d","isActive":true,"selected":true}]}

Then name it on each request:

curl -s -H "Authorization: Bearer $OPENCONSOLE_API_KEY" -H "X-OpenConsole-Cluster: k3d" \
"$OC_URL/api/namespaces/crashlab/pods" \
| jq -r '.items[] | [.metadata.name, .status.phase, .status.containerStatuses[0].restartCount] | @tsv'
agent-598r8 Running 0
badimage-67b7966bb-82lhs Pending 0
brokendb-0 Running 6
db-0 Running 0
db-1 Running 0
…

Lists return the Kubernetes objects as the API server sends them (metadata, spec, status) under items.

4. Read a log​

curl -s -H "Authorization: Bearer $OPENCONSOLE_API_KEY" \
"$OC_URL/api/namespaces/crashlab/pods/exit1-6bb6b857dc-bbcxg/logs?container=app&previous=true&tailLines=5"
starting
fatal: config missing

Plain text. previous=true is the container run before the current one (the one that crashed); tailLines defaults to 500. Right after a restart Kubernetes may answer unable to retrieve container logs for containerd://… for a while, like kubectl logs --previous does: if the container is in Error now, read without previous.

5. Run one command​

Needs pods:exec on the key (the Read-only templates don't have it):

curl -s -H "Authorization: Bearer $OPENCONSOLE_API_KEY" -H "Content-Type: application/json" \
-d '{"container": "app", "command": ["uname", "-sr"], "timeoutSeconds": 30}' \
"$OC_URL/api/namespaces/crashlab/pods/healthy-66fb4fb769-4cjqs/exec"
{"stdout":"Linux 6.8.0-110-generic\n","stderr":"","exitCode":0,"truncated":false,"durationMs":496}

command is an argv array, not run in a shell (["sh", "-c", "…"] for pipes). A non-zero exit code is still a 200. The command is recorded like a shell session; the audit event keeps only the program (uname), never the arguments.

Errors​

Every refusal is audited. An error answer is JSON in the problem details format of RFC 9457, with Content-Type: application/problem+json:

{"type":"about:blank","title":"Bad Request","status":400,"error":"invalid_input","detail":"cluster \"nope\" is unknown or not yours to use"}
  • error is always a reason code (snake_case): switch on it.
  • detail (not always there) is English text for a person: which field, which name. Show or log it; don't parse it.
  • title is the HTTP status text, type is always about:blank.

The API has no version in its path. It only grows (new fields, new codes, new endpoints), so ignore what you don't know; info.version in /api/openapi.json is the server's version. An unknown /api/… path answers 404 not_found, a known path with the wrong method 405 method_not_allowed with an Allow header.

StatuserrorMeans
401unauthorizedNo key, an unknown key, or its owner is disabled.
401api_key_expired / api_key_revokedThe key has expired / was revoked.
403password_change_requiredThe owner must change their password (first sign-in or an admin reset).
403forbiddenThe key doesn't list it, or you don't hold it in that namespace.
403api_access_policyYou hold it on the web, but the admin's API access policy keeps it from keys.
403api_access_offThe policy gives your keys nothing; every call is refused, /api/auth/me too.
403api_key_not_allowedWeb session only (managing keys, password, saved views).
403feature_disabledThe operator switched the feature off (FEATURE_*=false).
403admin_onlyAn admin endpoint, and the key isn't an Admin API key of an admin.
400invalid_inputA value isn't accepted; detail says which. For example X-OpenConsole-Cluster names a cluster that doesn't exist (403 forbidden for one the key doesn't cover).
404not_found / pod_not_foundThe object or the path doesn't exist.
403cluster_forbiddenThe cluster refused the read: OpenConsole's ClusterRole there doesn't allow it.
502 / 503 / 504cluster_unreachable / not_connected / cluster_timeoutThe cluster can't be reached or refused OpenConsole's credentials / isn't connected / didn't answer in time.
429rate_limitedMore than 10 requests a second for this key; wait for Retry-After (1 second). See Limits.

Every code: Troubleshooting → Error answers.

Seen on the test cluster with:

curl -s -w ' %{http_code}\n' -H "Authorization: Bearer $OPENCONSOLE_API_KEY" "$OC_URL/api/namespaces/kube-system/pods"
# {"type":"about:blank","title":"Forbidden","status":403,"error":"forbidden"}
# 403
curl -s -w ' %{http_code}\n' -H "Authorization: Bearer $OPENCONSOLE_API_KEY" "$OC_URL/api/me/api-keys"
# {"type":"about:blank","title":"Forbidden","status":403,"error":"api_key_not_allowed"}
# 403
curl -s -w ' %{http_code}\n' -H "Authorization: Bearer $OPENCONSOLE_API_KEY" -H "X-OpenConsole-Cluster: nope" \
"$OC_URL/api/namespaces/crashlab/pods"
# {"type":"about:blank","title":"Bad Request","status":400,"error":"invalid_input","detail":"cluster \"nope\" is unknown or not yours to use"}
# 400
curl -s -w ' %{http_code}\n' -H "Authorization: Bearer $OPENCONSOLE_API_KEY" "$OC_URL/api/admin/users"
# {"type":"about:blank","title":"Forbidden","status":403,"error":"admin_only"}
# 403
curl -s -w ' %{http_code}\n' -H "Authorization: Bearer oc_notarealkey" "$OC_URL/api/auth/me"
# {"type":"about:blank","title":"Unauthorized","status":401,"error":"unauthorized"}
# 401
curl -s -i -X DELETE -H "Authorization: Bearer $OPENCONSOLE_API_KEY" "$OC_URL/api/namespaces/crashlab/pods" | grep -E '^(HTTP|Allow)|"error"'
# HTTP/1.1 405 Method Not Allowed
# Allow: GET
# {"type":"about:blank","title":"Method Not Allowed","status":405,"error":"method_not_allowed"}

Next: give it to an agent: Agent recipes. Every endpoint: endpoint reference.