#me apikey

Manage API keys — your own personal access token (PAT) or a key for a service account (--service).

An API key is a global, per-principal credential — not inherently bound to a space. An unrestricted key works in any space its principal has been admitted to. A restricted key works only in its declared spaces and is capped to any declared tree grants; the space comes from the X-Me-Space header (ME_SPACE or the selected active space). Keys are formatted me.<lookupId>.<secret>.

There are two access modes: an unrestricted key acts with all of its holder's current authority, while a restricted key is capped to declared spaces and optional tree grants. Both modes can be held by the following principals:

  • Personal access token (default) — acts as you, for headless/CLI use (a VM, SSH, CI) where your me login session isn't available. It can be unrestricted or restricted with --allow, but it cannot manage keys (minting/revoking always needs a session).
  • Service-account key (--service <service>) — acts as a space-scoped service account, for CI/CD jobs, webhooks, and other team-owned integrations. Treat it like a production secret.

Minting and revoking keys authenticate with your session (me login); an API key can't mint or revoke keys. The CLI never persists API keys — a created key is printed once for you to place where it's used (typically the ME_API_KEY environment variable). The alias me apikey revoke is equivalent to me apikey delete.

#Commands

#me apikey create

Mint a new API key. With no target option, mints a personal access token for yourself; with --service, mints a key for that service account in the active space. The raw key is shown only once — store it securely.

me apikey create [name] [--service <service>] [--expires <timestamp> | --ttl <duration>] [--allow <scope>] [--space-admin <space>]
Argument Required Description
name no Key name (auto-generated as cli-<date>-<rand> if omitted).
Option Description
--service <service> Mint a key for a service account (id or name) in the active space.
--expires <timestamp> Expiration timestamp (ISO 8601).
--ttl <duration> Expiration from now, e.g. 30d, 24h, 30m.
--allow <scope> Repeatable restricted-access declaration: <space> permits all of the holder's current effective access there; <space>:<path>:<r|w|o> sets a tree ceiling. Use . for the active space.
--space-admin <space> Repeatable: permit space-admin authority in a declared space, but only when the holder is actually an admin.

Names are unique per principal, so you can't mint two keys with the same name for the same target. The auto-generated default carries a random suffix, making repeated me apikey create calls extremely unlikely to collide.

# A personal access token for yourself (e.g. to use headlessly in a VM)
me apikey create
me apikey create my-laptop          # …with a name
me apikey create vm-key --ttl 30d   # expires 30 days from now

# A key for a service account in the active space
me apikey create --service deploy-bot ci-key

# A PAT restricted to deployment writes in one space
me apikey create deploy --allow .:/share/deploy:w

# A key with all of the holder's current access in a declared space
me apikey create ci --allow abc123def456

--allow creates a restricted key and must appear at least once. A bare and a tree-specific declaration cannot be combined for the same space. Service-account keys may declare only their native active space. Restricted scope is immutable: create a replacement key, deploy and verify it, then revoke the old key.

#me apikey list

List API keys (metadata only — never the secret). With no target option, lists your own keys; with --service, lists that service account's keys in the active space. Alias: me apikey ls.

me apikey list [--service <service>]
Option Description
--service <service> List a service account's keys (id or name) in the active space.

Displays a table of keys with ID, name, scope (full or restricted), created date, expiry, and last-used date.

Last used is tracked at day resolution (YYYY-MM-DD) in UTC. It updates at most once per key per UTC day per server process, so it is intended for operational visibility rather than precise audit logging.

#me apikey get

Show metadata for a single API key.

me apikey get <id>
Argument Required Description
id yes API key ID.

For restricted keys, this also shows every declared space, optional admin cap, and tree grant. A declaration with no tree grants is shown as all holder access: it follows the holder's live effective access in that space.

#me apikey delete

Permanently delete (revoke) an API key. There is no soft-revoke state — delete is the only way to invalidate a key. Irreversible. Aliases: me apikey rm, me apikey revoke.

me apikey delete <id> [-y]
Argument Required Description
id yes API key ID.
Option Description
-y, --yes Skip the confirmation prompt.

#See also

  • me service -- create service accounts that hold --service keys.
  • MCP Integration -- supply a key to an MCP-connected agent via --api-key or ME_API_KEY.
  • Harness Integrations -- managed harnesses and machine-local configuration.