Get a credential

Every server call needs a bearer credential, and a fresh deployment has none. The CLI is what mints the first one, because minting requires the private key the server validates against - which makes holding that key the operator credential.

There are two kinds:

• A user JWT is your identity. Long-lived, minted locally from the RS256 private key, never seen by the server until you use it.
• An API key (axl_key_…) is a credential for something that is not you - a script, a CI job, a bot. Created through the server, revocable, and never broader than the token that created it.

Mint a user JWT

If the deployment has no keypair yet:

axl key generate-jwt        # ~/.axl/keys/jwt_{private,public}.pem

Put the public half in the server's JWT_PUBLIC_KEY and the private half in JWT_PRIVATE_KEY. Then mint against it:

axl config init \
  --jwt-private-key ~/.axl/keys/jwt_private.pem \
  --user-id you@example.com \
  --role admin

The token is saved into the profile in use, so nothing needs to be copied anywhere. Re-running config init refreshes the token and leaves the rest of the profile alone.

What goes in the token

Passing the axl: prefix yourself on --user-id produces axl:axl:you, which authenticates as a principal that owns nothing.

Roles are not scopes

They answer different questions:

• A scope narrows what this token may reach. It can be granted below the authority of the person holding it - that is the point of handing one to a script.
• A platform role is a property of the principal. admin means the principal may act outside their own data, which is what the diagnostics boards need in order to show every principal's runs rather than only yours.

An organization role is a third axis again: an org admin is not a platform admin.

# An operator credential for the console
axl config init --user-id you@example.com --role admin \
  --scopes agent:read,agent:write,diagnostics:read

Hand out an API key

API keys are created through the server, so they need a working credential first. The secret is shown once, at creation, and never again:

axl token create --scopes agent:read --name ci-bot --ttl-days 30
axl token list                 # metadata only, never the secret
axl token revoke <prefix>      # the prefix printed at creation

--ttl-days 0 creates a non-expiring key; omitting it gives the 90-day default. The scopes must be a subset of your own token's - the server refuses to mint a key more powerful than the credential asking for it.

Check what you are holding

axl config show

decodes the token locally and prints its subject, issuer, and expiry. That is a decode, not a validation: it tells you what the credential asserts, not whether the server accepts it. The first real answer is any call that reaches the server.

axl agents list        # 401 here means the server disagrees

A 401 with a token that looks right is almost always one of four mismatches: kid, iss, aud, or the public key itself. axl config show prints the first three.

Next

• Point the CLI at a deployment - store the credential and switch between servers.
• Command reference - every flag on config, key, and token.
• Authentication and authorization - how the server evaluates what it receives.