Skip to main content

API keys CLI

Use the api_keys command group to create secrets without opening the admin UI. Each key you mint through the CLI is scoped by tenant, organization, and roles—mirroring the UI workflow described in the Managing API keys guide.

Command reference​

mercato api_keys add​

Create a new API key and print the secret one time.

yarn mercato api_keys add \
  --name "CI deployer" \
  --tenantId 4c1378aa-1d27-4bc5-9a82-5afecf05c8f3 \
  --organizationId 6b4b3a5d-9a5d-4fcf-927f-830e1d9b3eee \
  --roles admin,employee \
  --description "Deployments from GitHub Actions" \
  --expiresAt 2025-12-31T23:59:59Z

Flags

  • --name (required) – human-friendly label that appears in the admin table.
  • --tenantId (required unless --organizationId resolves to a tenant) – UUID of the tenant the key should impersonate.
  • --organizationId (optional) – UUID of the organization the key should limit itself to.
  • --roles (optional) – comma-separated list of role IDs or role names to attach to the key.
  • --description (optional) – short memo that helps your teammates remember why the key exists.
  • --expiresAt (optional) – ISO timestamp after which the key can no longer authenticate.

The CLI prints:

API key created:
  id: 1d7fdd99-2081-4a4e-b50f-2a5f6670bcab
  name: CI deployer
  tenantId: 4c1378aa-1d27-4bc5-9a82-5afecf05c8f3
  organizationId: 6b4b3a5d-9a5d-4fcf-927f-830e1d9b3eee
  keyPrefix: omk_live_j1s8

Secret (store immediately):
omk_live_j1s8.9S1xk7tQ0OpvLkVd8AI9hpH7Qq3MxG9N
  • Save the secret in your vault. You cannot retrieve it again.
  • The prefix stays visible in the admin UI, helping you identify which script owns the key.
  • Rotate keys by creating a replacement secret, updating your automation, then deleting the old key through the UI or API.

Operational tips​

  • Pair keys with scoped roles that only include the features your automation requires (for example api_keys.view is usually unnecessary).
  • Prefer short expirations for temporary projects and schedule replacements before the cutoff.
  • Enable audit logging on your infrastructure so you can map outgoing requests back to key prefixes quickly.