CLI Reference: API Keys

Commands for creating and managing API tokens that grant HTTP access to the agentd API Gateway.

See API Gateway for the full HTTP API reference.

ash api-key create

Create a new API token and bind it to an agent.

ash api-key create --name <name> --agent-id <uuid>
FlagRequiredDescription
--nameYesHuman-readable label for this token
--agent-idYesUUID of the agent this token is bound to

On success, prints the token once. The plaintext token is never stored; only its SHA-256 hash is persisted. Save it immediately.

Created API key 'my-token'
Agent: 550e8400-e29b-41d4-a716-446655440000

Token: a3f8c2e1d4b7...  (64 hex chars)

Save this token. It will not be shown again.

Every HTTP request authenticated with this token is attributed to the bound agent. The bound agent's ID is used for capability checks and audit log entries.

Example:

ash api-key create --name "ci-pipeline" --agent-id 550e8400-e29b-41d4-a716-446655440000

ash api-key list / ash api-key ls

List all registered API keys. Token values are never shown; only the key name, bound agent, and creation timestamp are listed.

ash api-key list
ash api-key ls   # alias

Output columns: NAME, AGENT ID, CREATED.

NAME          AGENT ID                              CREATED
ci-pipeline   550e8400-e29b-41d4-a716-446655440000  2026-02-22T10:00:00Z
monitoring    a1b2c3d4-e5f6-7890-abcd-ef1234567890  2026-02-21T08:30:00Z

ash api-key revoke

Revoke an API key by name. The token immediately becomes invalid for all future requests.

ash api-key revoke <name>
ArgumentDescription
nameName of the key to revoke (as given to api-key create)

Example:

ash api-key revoke ci-pipeline

Revocation is permanent. To restore access, create a new key with ash api-key create.