Skip to main content
Cloacina Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage
  1. Cloacina
  2. /
  3. Run the Service
  4. /
  5. How-to Guides
  6. /
  7. Manage API Keys

Manage API Keys

Manage API Keys

API keys authenticate every call to the cloacina-server HTTP API. This guide covers creating, listing, and revoking them with cloacinactl (and the equivalent REST endpoints). For the trust model behind keys, roles, and the bootstrap key, see Security Model.

Prerequisites

  • cloacinactl installed and a reachable server.
  • An admin key to authenticate with — on first startup the server writes a bootstrap admin key once to ~/.cloacina/bootstrap-key (see Deploy a Server).

Either pass --server/--api-key on each command or save a profile (see Use CLI Profiles).

Create a key 

cloacinactl key create ci-bot --role write \
  --server http://127.0.0.1:8080 --api-key "$ADMIN_KEY"

--role is one of read, write, or admin (default read). The response prints the secret once — store it immediately; it cannot be retrieved again.

Tenant scope: the new key is scoped to the tenant of the key you authenticate with. To mint a key for a specific tenant, authenticate with an admin key and pass the global --tenant <name> flag:

cloacinactl key create acme-bot --role write --tenant acme \
  --server http://127.0.0.1:8080 --api-key "$ADMIN_KEY"

List keys 

cloacinactl key list --server http://127.0.0.1:8080 --api-key "$ADMIN_KEY"

Add --output json for scripting. Secrets are never returned — only key ids, names, roles, and metadata.

Revoke a key 

cloacinactl key revoke <key-id> --server http://127.0.0.1:8080 --api-key "$ADMIN_KEY"

Revocation is immediate. The CLI prompts for confirmation; pass --force to skip it in automation.

REST equivalents

The CLI is a thin wrapper over these endpoints (full details in the HTTP API Reference):

Action Method + path
Create POST /v1/auth/keys (body: { "name": ..., "role": ... }; tenant scope from the calling key)
List GET /v1/auth/keys
Revoke DELETE /v1/auth/keys/{key_id}

POST /v1/tenants/{tenant_id}/keys is also available for admin-key callers that need to name the target tenant explicitly.

See also

gdoc_arrow_left_alt Creating Your First Package Safely Unload a Package gdoc_arrow_right_alt