API keys

API keys are project-scoped credentials for your own services. They are separate from Account Service Keys, which authenticate the CLI itself. Browse the automatic command reference.

Create a key

Every key needs a name of at most 128 characters and an explicit expiry decision, plus one or more explicit permissions. RFC 3339 timestamps are normalized to UTC. Replace the example expiry with a future timestamp when running the command.

photon project api-key create \
  --name production-worker \
  --permission events:write \
  --expires-at 2027-09-01T00:00:00Z

photon project api-key create --name legacy-worker --permission project:read --no-expiry

{"apiKey":{"apiKeyId":"api_key_123","name":"production-worker","projectId":"project_123","createdByAccountId":"account_123","createdAt":"2026-08-01T18:00:00.000Z","expiresAt":"2027-09-01T00:00:00.000Z","revokedAt":null,"permissions":["events:write"],"permissionsUpdatedAt":null},"secret":"..."}

Creation is the only command that returns the secret. It is printed once on stdout with a save-now warning on stderr, and never appears in list, revoke, errors, --debug output, or the local journal. Send it straight to a secrets manager — not into source control or a project config file.

Supported permissions are events:read, events:write, platforms:read, platforms:write, project:read, and project:write. Repeat --permission for each permission the service needs. No permissions are granted implicitly. List and create output include permissions and permissionsUpdatedAt.

List keys

photon project api-key list
photon project api-key list --json

api-key list returns live keys only, so revoked keys drop out of later lists. It is not paginated — the API returns every live key, newest first.

Revoke a key

photon project api-key revoke api_key_123

revoke accepts either the public API key ID or the full credential; the CLI extracts the public ID before confirming, journaling, or sending the request.

Prefer the public ID. Command-line arguments can persist in shell history and are visible to other local processes.

Rotate safely

Rotation is deliberately not one command, because a single atomic swap gives you no window to verify the replacement:

Create a replacement key

photon project api-key create --name production-worker-2 --permission events:write --no-expiry

Update your consumers

Deploy the new secret everywhere the old one is used.

Verify the replacement

Confirm traffic is flowing with the new key before going further.

Revoke the old key

photon project api-key revoke api_key_123 --force

Get started

Projects

Account

Compliance

Reference

Create a key

List keys

Revoke a key

Rotate safely

​Create a key

​List keys

​Revoke a key

​Rotate safely

Create a key

List keys

Revoke a key

Rotate safely