API Keys

API keys authenticate requests to an instance's data API. They are scoped to one environment and one capability set.

Key scopes

Scope	Use
read	Read aggregates, events, and projections
write	Read data and write events
deploy	Deploy specs and projections; no application-data access

Use the narrowest scope that fits the job. See API authentication for the complete authorization model.

List keys

j17 key list
j17 key list --env staging
j17 key list --instance my-app --env prod

Without an explicit override, the command uses the instance and environment saved by j17 use. When an environment is selected, the CLI filters the result to that environment.

The list shows key metadata and prefixes, never raw key secrets.

Create a key

j17 key create local-backend --scope write
j17 key create ci-deploy --scope deploy --env test

Creation requires an instance and environment, either from the saved selection or from --instance and --env.

The raw key is returned exactly once. In normal output mode it is the only value written to stdout; progress and the copy warning go to stderr. Save it immediately in your secret manager:

J17_API_KEY="$(j17 key create local-backend --scope write)"
export J17_API_KEY

The CLI does not store generated API keys in its configuration or credentials files.

For a structured response containing both metadata and raw_key:

j17 key create ci-deploy --scope deploy --env test --json

Rotate a key

Rotation creates a new key and schedules the old key for revocation:

j17 key rotate KEY_ID
j17 key rotate KEY_ID --grace 4

--grace is a non-negative number of hours. If omitted, the server's default grace period applies. A grace period of 0 revokes the old key without an overlap window.

The new raw key is shown exactly once and is not persisted by the CLI. Update consumers during the overlap window, then allow the old key to expire.

Revoke a key

j17 key revoke KEY_ID

The command asks for confirmation. In non-interactive automation, acknowledge the destructive action explicitly:

j17 key revoke KEY_ID --yes
# or
j17 key revoke KEY_ID -y

Rotation and revocation use a key ID, not a key prefix or raw secret. Obtain IDs with j17 key list.

Keep raw keys out of logs

Human-readable create and rotate commands put the raw key on stdout so it can be captured separately from diagnostics. --json also includes the raw key; treat that entire JSON response as a secret and do not archive it as ordinary CI output.