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

# OAuth clients

> Manage the OAuth applications your organization owns and their client secrets.

OAuth clients are applications owned by an organization. They use the
[selected organization](/docs/beta/cli/organizations#select-an-organization). Applications
*you* have authorized are account connections, listed under
[`photon account oauth`](/docs/beta/cli/accounts/oauth).

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

## Clients

```sh theme={null}
photon org oauth-client list
photon org oauth-client view client_123

photon org oauth-client create \
  --name "Acme Integration" \
  --redirect-uri https://acme.example/callback \
  --default-redirect-uri https://acme.example/callback \
  --scope account:read \
  --scope project:read
```

`--redirect-uri` and `--scope` are repeatable; without `--scope` the client has
no delegated scopes. The default redirect must exactly match one of the
supplied redirect URIs. Redirect URIs must use HTTPS, except for HTTP loopback
URLs during development. User info, fragments, duplicates, and more than ten
redirect URIs are rejected before the request is sent.

Creation sends an idempotency key, generated unless you pass
`--idempotency-key`. If the outcome is uncertain — the connection dropped or
Photon answered with a server error — the error names the key: retry the same
command with it rather than a new one, and Photon returns the client the first
request created.

`update` replaces redirect URIs or scopes when you supply them. Use
`--clear-description` or `--clear-scopes` to remove those values:

```sh theme={null}
photon org oauth-client update client_123 --name "New name"
photon org oauth-client update client_123 \
  --redirect-uri https://new.example/callback \
  --default-redirect-uri https://new.example/callback
photon org oauth-client delete client_123 --force
```

`delete` reports `status`. When Photon has accepted the deletion but provider
cleanup is still pending, the CLI warns that existing tokens may keep working
until it completes.

## Test an authorization

`authorize` builds an authorization-code request and opens it, which is the
fastest way to check a client's redirect URIs and scopes:

```sh theme={null}
photon org oauth-client authorize client_123

photon org oauth-client authorize client_123 \
  --redirect-uri http://localhost:3000/callback \
  --scope account:read \
  --no-browser
```

It reads the scope catalogue, discovers the authorization server through
Photon's protected-resource metadata, reads the client, and validates the
redirect URI and scopes before opening anything. With the options omitted, it
uses the client's default redirect URI and configured scopes.

<Note>
  This helper only generates the authorization URL, state, and nonce. Your
  registered application handles the callback and exchanges the code with its
  own client secret — the CLI never accepts or stores that secret.
</Note>

## Secrets

```sh theme={null}
photon org oauth-client secret list client_123
photon org oauth-client secret create client_123
photon org oauth-client secret revoke client_123 secret_123 --force
```

`secret list` returns metadata only, including `revokesAt` for a secret whose
revocation is scheduled.

```json theme={null}
{"clientId":"client_123","secretId":"secret_123","secret":"..."}
```

<Warning>
  `secret create` prints the plaintext secret **once**. Save it immediately.
  Photon never stores it locally, and `--debug` output redacts the response.

  Secret creation is not journaled, and the plaintext is never stored. After an
  uncertain failure, retry with the `--idempotency-key` the error names: Photon
  then reports the earlier attempt's status instead of creating a second
  secret, and the CLI reports `OAUTH_SECRET_NOT_DELIVERED`. Plaintext is only
  returned to the request that created the secret, so if it was lost, revoke
  that secret from `secret list` and create a replacement.
</Warning>

<Note>
  These commands replaced `photon account oauth client` and
  `photon account oauth secret`, which now only point here.
</Note>


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