Tillered Docs | Credential management

Rotate, create, and revoke the shared OAuth credentials your operators use to reach the cluster

The shared cluster credential

Every Arctic agent authenticates operator requests with OAuth2 client credentials: a client ID (prefixed cli_) and a client secret (prefixed sec_). The cluster shares one of these credentials across all peers and replicates it through gossip, so an operator can point the CLI at any agent with the same client_id and client_secret and be authenticated everywhere.

Because the secret is shared, rotating it is a cluster-wide event with a deadline. The rest of this page covers listing, creating, revoking, and rotating credentials.

List credentials

List the API credentials known to the cluster:

arctic credentials list

curl -X GET http://AGENT_IP:8080/v1/credentials \
  -H "Authorization: Bearer $TOKEN"

The response wraps the list under a credentials array. Client secrets are never returned by list; they are shown only once at creation time.

Each entry shows the client_id, its scopes, the license_id, and timestamps. Secrets are never displayed.

Create a credential

Mint a new credential, optionally scoped down from the full set:

# Inherits the scopes of the credential making the request
arctic credentials create

# Scoped to read-only peer and service access
arctic credentials create --scopes peers.read,services.read

curl -X POST http://AGENT_IP:8080/v1/credentials \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["peers.read", "services.read"]}'

Save the secret now

The client_secret is returned exactly once, at creation. It cannot be recovered later. Store it in your secret manager immediately.

Use scoped credentials for automation that only needs part of the API. Grant least privilege; reserve admin for break-glass use.

Revoke a credential

Revoke (tombstone) a credential by its client ID:

arctic credentials revoke cli_THE_CLIENT_ID

curl -X DELETE http://AGENT_IP:8080/v1/credentials/cli_THE_CLIENT_ID \
  -H "Authorization: Bearer $TOKEN"

Revocation propagates across the cluster as a signed tombstone, so the credential stops working on every peer.

You cannot revoke yourself

The agent refuses to revoke the credential that is currently authenticating the request, so you cannot lock yourself out with a single command.

Rotate the cluster credential

Rotation replaces the shared secret with a new one. Any peer can run it.

arctic credentials rotate

To keep the operator who rotated authenticated, write the new secret into the local CLI config in the same step:

arctic credentials rotate --update-config

curl -X POST http://AGENT_IP:8080/v1/cluster/credentials/rotate \
  -H "Authorization: Bearer $TOKEN"

The response returns the new client_id, the new one-time client_secret, and the bumped version. Capture the secret immediately.

When you rotate:

A new secret is minted and gossiped to every cluster peer.
The previous secret's hash stays accepted for a 24-hour propagation window.
After the window, the previous secret expires and stops working everywhere.

The propagation window exists so the new secret has time to reach all peers and so operators have time to pick it up. It is not a grace period you should rely on for day-to-day access.

24-hour deadline

You MUST redistribute the new client_secret to every operator and automation that uses the shared credential within 24 hours. When the window closes, the previous secret expires and anyone still using it is locked out of the cluster.

Recommended rotation procedure

Rotate from a peer you control, keeping yourself authenticated:
```
arctic credentials rotate --update-config
```
Capture the new secret from the command output (or the client_secret in the API response) and store it in your secret manager. It is shown only once.
Distribute the new secret to every operator and automation that authenticates against the cluster: CI/CD pipelines, scripts, teammates' CLI configs, and any external tooling.
Update each consumer's config before the window closes. Operators who did not run the rotation can write the new secret into their own CLI config and verify access:
```
arctic credentials list
```
Confirm convergence within the 24-hour window. Every consumer should be using the new secret well before the previous one expires.

Troubleshooting

Locked out after rotation

If the 24-hour window has closed and you are still using the previous secret, you can no longer authenticate with it. Obtain the current secret from whoever rotated it (or your secret manager) and update your CLI config. If the secret is lost entirely, rotate again from a peer that still has a working credential.

Operator who rotated is locked out

This happens when rotate is run without --update-config and the local config keeps the old secret. Re-run with --update-config, or manually write the new client_secret into the CLI config, while a working token is still available.

Permission denied

Rotating, creating, and revoking credentials require the credentials.write scope. Verify your credential's scopes with arctic credentials list.

Credential management