Give an agent machine access
Get a non-interactive client — an agent, a CI pipeline, a script — talking to Kairos without a person or a browser in the loop, and able to rotate its credential without downtime.
An agent that works for you, for example Claude Code, does not need a service account. Give it your own agent key: see Give an agent your key.
Before you start: you are an organization admin. To create service accounts,
to mint keys and to revoke them are all org-admin only. Do not plan around your
issuer’s client_credentials grant. Kairos issues its own API keys instead, and
Dex — the reference issuer — does not support that grant at all.
A service account’s id is an ordinary user_id. Thus team membership and
capability grants work on it exactly as they do for a person.
1. Create the service account
Section titled “1. Create the service account”kairos service-accounts create --name ci-deploy# → Kairos made the service account ci-deploy (a1b2c3…).Or POST /api/service-accounts with {"name":"ci-deploy"}.
Keep the id. Every key command needs it.
2. Give it somewhere to work, and only what it needs
Section titled “2. Give it somewhere to work, and only what it needs”Put it on the team whose board it works:
kairos teams members add <team-id> --user a1b2c3…Then grant it the narrowest capability that does its job. For example, something
that only moves cards gets transition_items on one delivery board, never a
manage_*.
Grants are per board. Use kairos grants add --user <id> --capability transition_items --board <board>,
POST /api/boards/{id}/members or the
board members panel of the GUI. The vocabulary is in
Capabilities.
A service account can never be an organization admin or a deployment admin.
It can hold manage_structure: the work on teams and boards of an organization
admin, and no more. See Run an admin agent.
3. Mint a key
Section titled “3. Mint a key”kairos keys create --service-account a1b2c3… --name gha-main \ --expires-at 2027-01-01T00:00:00Z## kairos_sk_acme_9f8e7d6c5b4a… ← copy it now## Keep the key in a safe place now. Kairos does NOT show it again.The raw key is shown exactly once. Kairos stores only a SHA-256 hash, so there
is no “show me that key again”. kairos keys list returns prefixes and
nothing else. Put it straight into the secret store the client reads from. If
you lose it, mint another and revoke the old one; that is step 5 anyway.
--expires-at is optional and worth setting. Expiry takes effect immediately on
the next request, with no sweeper involved.
4. Use it
Section titled “4. Use it”The key goes in an ordinary Authorization: Bearer header, and carries its own
tenant — no X-Tenant, no login, no token refresh:
curl https://<host>/api/whoami \ -H "Authorization: Bearer kairos_sk_acme_9f8e7d6c5b4a…"It works identically on /api, /mcp and /ws, subject to the same access
control as a member. For an agent, point the MCP client’s bearer at it. Then the
whole tool surface is available, with no browser OAuth dance — see
Connect over MCP.
whoami naming the service account is the check that the wiring is complete.
Kairos attributes the writes it makes to it in the activity feed, as a principal
in its own right. That is what makes “who deployed that?” answerable.
5. Rotate without downtime
Section titled “5. Rotate without downtime”Two keys can be live at once, and that is the whole mechanism:
kairos keys create --service-account a1b2c3… --name rotation # both now work# …switch the client over to the new key, and confirm it is using it…kairos keys revoke <old-key-id> --service-account a1b2c3… --confirmDo it in that order. Revocation lands immediately on the next request. Thus to revoke first is an outage; to mint first is not. The revocation is surgical — the account’s other keys keep working. Thus responding to a leak does not take the pipeline down.
6. Retire the account
Section titled “6. Retire the account”kairos service-accounts delete a1b2c3… --confirmThis kills every key it holds, immediately. Deleting the account is therefore the blunt instrument for a compromise you cannot attribute to one key. For a single leaked key, revoke that key instead.
Never commit a key to source control — add the kairos_sk_ prefix to your
secret scanner.