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

Environment	Use
Local desktop, interactive	`ox login`
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

Sign in at sageox.ai.
Open Settings → Tokens.
Click Create token.
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.
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.
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.

Use the token

Export SAGEOX_TOKEN in the environment where ox runs:

terminal

# Set the token (paste yours after the equals sign)

# Verify authentication

# Prime an AI coworker session

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

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.

For setup recipes in constrained environments (Claude Code Cloud, Devin, GitHub Actions), see Running ox in constrained environments.

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

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

Revoke from 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

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

Running ox in constrained environments — per-platform setup recipes
ox login — interactive desktop authentication
ox status — verify which credential is active
ox doctor — diagnose auth failures

On this page