API keys

Every credential a Ciresk API accepts, where each comes from, and how to send it.

Send a credential on every request as Authorization: Bearer <credential>. A product's GET /health and GET /ready probes need none.

Credential	Starts with	For	Lifetime
API key	`csk_live_eu_`	Scripts, servers, agent sandboxes. Created on platform.ciresk.com.	Until revoked or its expiry; a revocation is effective within 60 s.
Exchanged token	`cix_`	GitHub Actions jobs, through Ciresk CI's exchange endpoint.	1 hour.
Person token		What `ciresk ci auth login` keeps in the OS keychain and MCP clients obtain through OAuth. Not for scripts.	Refreshed in the keychain.
Worker token	`ciw_`	Ciresk CI workers only, from `ciresk-ci-worker join`.	24 hours, renewed on a heartbeat before it runs out; revoked on deregister.

A credential belongs to one organization and carries its region, so no organization header is needed.

Create a key

Open platform.ciresk.com and go to API tokens for a token that acts for the organization, or My profile › API tokens for one that acts as you.
Select Create token, then a template or Create custom token.
Name it, add a permission policy with the permissions it needs (for Ciresk CI, see Scopes) and an expiry of at most 90 days, then select Review token and Create token.
Copy the token. It is shown once; the platform keeps only a fingerprint.

The key starts with csk_live_eu_ for an organization in the EU region. A product introspects it by fingerprint at the platform and caches the answer for 60 s; the product does not store the key or its hash. Revoke it on the same page; apps using it lose access within 60 s.

Ciresk CI example

export CIRESK_API=https://ci.eu.ciresk.com
export CIRESK_KEY=csk_live_eu_...
curl -s "$CIRESK_API/v1/ci/budget" -H "Authorization: Bearer $CIRESK_KEY"

In Ciresk CI, GET /v1/ci/budget answers the principal behind the credential (kind, org_id, jurisdiction, the key's prefix and scopes), its budget and the policy that applies: the quickest way to check a key there. The platform's own call is GET https://api.ciresk.com/v1/platform/keys/whoami, and keys themselves are minted, rotated and revoked through the Platform API.

Exchange an OIDC token

A job in GitHub Actions trades its OIDC token for a one-hour token instead of holding a key, through Ciresk CI's POST /v1/ci/auth/exchange:

Ciresk CI example

curl -s -X POST "$CIRESK_API/v1/ci/auth/exchange" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: exchange-$GITHUB_RUN_ID" \
  -d '{"token": "'"$OIDC_TOKEN"'", "requested_scopes": ["ci:jobs.run", "ci:jobs.read", "ci:repos.read", "ci:blobs.read", "ci:blobs.write"]}'

The answer carries token (cix_...), expires_at and the principal; Ciresk CI adds the trust tier the token's jobs run as. Your organization's trust rule maps the token's repository and ref to a principal and decides which scopes it may have; asking for a scope outside that is 403 insufficient_scope, and a repository with no rule is 401 oidc_rejected with reason: unknown_repo. The Ciresk CI GitHub Action does the exchange for you and never writes the token to a log or an output.

Rotation and revocation

Revoke a key on platform.ciresk.com; create a new one first when something depends on it.
Exchanged tokens expire with the hour and cannot be revoked separately.
A Ciresk CI worker token is replaced on a heartbeat when it has less than 4 hours left, and the old one stays valid for 5 minutes; ciresk-ci-worker keeps it in /var/lib/ciresk-ci/state.json, readable by root only.
A person's token lives in the OS keychain; ciresk ci auth logout removes it.