# Personal Access Tokens (/docs/cli/pats)



Personal Access Tokens [#personal-access-tokens]

Long-lived tokens for using ox in CI, cloud agents, and scripts. PATs authenticate `ox` in environments where the interactive [`ox login`](/docs/cli/auth) device flow is not possible — cloud coding agents, CI runners, and unattended scripts.

A PAT is a long-lived bearer credential scoped to your SageOx account. Treat it like a password.

When to use a PAT [#when-to-use-a-pat]

| Environment                            | Use                          |
| -------------------------------------- | ---------------------------- |
| Local desktop, interactive             | [`ox login`](/docs/cli/auth) |
| Claude Code Cloud, Devin, Codespaces   | PAT                          |
| GitHub Actions, GitLab CI, Buildkite   | PAT                          |
| Headless scripts, cron, scheduled jobs | PAT                          |

`ox login` writes credentials to `~/.config/sageox/credentials.json` after a browser handshake. That flow does not work in cloud sandboxes where there is no browser, no persistent disk, and no way to open `localhost`. A PAT is the headless equivalent.

Create a token [#create-a-token]

1. Sign in at [sageox.ai](https://sageox.ai).
2. Open [**Settings → API Tokens**](https://sageox.ai/settings/tokens) (under the **Sharing** group).
3. Click **Create token**.
4. Give it a recognizable name — the name appears in audit logs and the revocation UI. Use something specific like `claude-cloud-acme-repo` or `github-actions-ci`, not `token1`.
5. Pick an expiration. Options are 7, 30, 60, 90 (default), 180, or 365 days, a custom value up to 365 days, or a deliberate "never expires" ceremony that requires typed confirmation.
6. Click **Create**. The token displays once. Copy it immediately — SageOx does not store the plaintext and cannot show it again.

Scopes are currently full account access. Scoped tokens are tracked in [SageOx roadmap](https://sageox.ai/roadmap).

Use the token [#use-the-token]

Export `SAGEOX_TOKEN` in the environment where `ox` runs:

<Terminal>
  <TerminalComment>
    Set the token (paste yours after the equals sign)
  </TerminalComment>

  <TerminalCommand>
    export SAGEOX_TOKEN=oxp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_yyyyyyyy
  </TerminalCommand>

  <TerminalComment>
    Verify authentication
  </TerminalComment>

  <TerminalCommand>
    ox status
  </TerminalCommand>

  <TerminalComment>
    Prime an AI coworker session
  </TerminalComment>

  <TerminalCommand>
    ox agent prime
  </TerminalCommand>
</Terminal>

`SAGEOX_TOKEN` is the only environment variable the CLI reads for PAT authentication. It takes precedence over any cached credentials from `ox login`.

<Callout type="info">
  **`OX_TOKEN` is no longer read.** Earlier releases accepted `OX_TOKEN` as an alias; the runtime now reads `SAGEOX_TOKEN` only. Update any CI secret or hook script that still sets `OX_TOKEN` — leaving it set will surface as `not authenticated` errors at the next `ox` invocation. See [ADR-047](https://github.com/sageox/sageox-mono/blob/main/docs/adr/047-sageox-token-rename.md).
</Callout>

For setup recipes in constrained environments (Claude Code Cloud, Devin, GitHub Actions), see [Running ox in constrained environments](/docs/cli/ephemeral-mode).

Token format [#token-format]

PATs follow a fixed shape:

```
oxp_<32-base62>_<crc32-base62>
```

* `oxp_` prefix — opaque marker that GitHub's, GitLab's, and TruffleHog's secret scanners recognize as a SageOx credential.
* 32 base62 characters of entropy.
* 8 base62 characters of CRC32 checksum so the CLI can reject malformed tokens before hitting the API.

The token is opaque. Do not parse it. Do not try to extract a user ID from it.

Expiration and rotation [#expiration-and-rotation]

* You receive an email when a token is created and when one is revoked.
* A reminder is sent 7 days before expiration.
* Never-expiring tokens get quarterly reminder emails so they do not disappear into forgotten secret stores.
* Rotate any PAT at least once per year. Short-lived secrets contain blast radius.
* When a token expires or is revoked, the next CLI call prints:

  ```
  SAGEOX_TOKEN expired or invalid — create a new one at https://sageox.ai/settings/tokens
  ```

  The exit code is non-zero so CI pipelines fail loudly rather than running unauthenticated.

There is no auto-refresh. PATs are intentionally simple — when one expires, generate a new one and update the secret in whatever platform stores it.

Revoking a token [#revoking-a-token]

Revoke from [**Settings → API Tokens**](https://sageox.ai/settings/tokens). Click the token row, then **Revoke**.

Revocation is immediate. There is no grace period. Any cloud agent or CI job using the token will start returning `401 Unauthorized` on the next request. Plan rotations so a new token is in place before revoking the old one.

If you suspect a token has leaked, revoke first and rotate second.

Security [#security]

* **Never commit a PAT to a repository.** GitHub, GitLab, and most secret scanners detect the `oxp_` prefix and notify SageOx, which will automatically revoke the token. Your CI will start failing within minutes.
* **Use platform secret stores**, not flags or shell history. Each cloud agent has a Secrets dashboard — see [Running ox in constrained environments](/docs/cli/ephemeral-mode) for per-platform instructions.
* **Pass via environment, not on the command line.** Anything in `argv` shows up in process listings (`ps`) and in some CI logs.
* **Scope by token, not by user.** Create one PAT per integration so you can revoke a leaked CI token without breaking your cloud agent.
* **Rotate after teammate offboarding.** If someone with access to your shared CI secrets leaves, rotate every PAT they could have read.

Related [#related]

* [Running ox in constrained environments](/docs/cli/ephemeral-mode) — per-platform setup recipes
* [ox login](/docs/cli/auth) — interactive desktop authentication
* [ox status](/docs/cli/status) — verify which credential is active
* [ox doctor](/docs/cli/doctor) — diagnose auth failures