> ## Documentation Index
> Fetch the complete documentation index at: https://docs.photon.codes/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use Stable documentation by default. Honor an explicit Beta request or a URL under /docs/beta/. If the requested version conflicts with the installed CLI package or API origin, clarify the target before writing integration code.
> Pages under /docs/beta/ document Beta; other product pages document Stable. Keep the CLI package, commands, API origin, and credentials within the selected version. State the documentation version in your answer.
> For MCP search, always pass version: Stable or version: Beta. Unfiltered search mixes both versions. For filesystem reads, keep Beta queries under /beta/ and exclude /beta/ from Stable queries; discover paths before reading them.
> The public docs base is https://photon.codes/docs. Convert MCP page paths to public URLs under that base, preserving /beta/ when present. Read https://photon.codes/docs/skill.md for version selection and https://photon.codes/docs/llms.txt for the version indexes.

# API keys

> Issue, rotate, and revoke project API keys.

API keys are project-scoped credentials for your own services. They are
separate from [Account Service Keys](/docs/beta/cli/service-keys), which authenticate the
CLI itself.

[Browse the automatic command reference](/docs/beta/cli/reference/index).

## 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.

```sh theme={null}
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
```

```json theme={null}
{"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":"..."}
```

<Warning>
  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.
</Warning>

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

```sh theme={null}
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

```sh theme={null}
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.

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

## Rotate safely

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

<Steps>
  <Step title="Create a replacement key">
    ```sh theme={null}
    photon project api-key create --name production-worker-2 --permission events:write --no-expiry
    ```
  </Step>

  <Step title="Update your consumers">
    Deploy the new secret everywhere the old one is used.
  </Step>

  <Step title="Verify the replacement">
    Confirm traffic is flowing with the new key before going further.
  </Step>

  <Step title="Revoke the old key">
    ```sh theme={null}
    photon project api-key revoke api_key_123 --force
    ```
  </Step>
</Steps>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.