Agents should use explicit environment authentication. It is easy to rotate, works in short-lived shells, and avoids hidden dependence on a developer's keychain.
Use environment auth#
REPOST_TOKEN has the highest priority. It overrides credentials saved by repost auth login or repost auth token.
export REPOST_TOKEN=rp_your_token_here
repost auth status --json
repost whoami --jsonVerify the token with repost auth status --json. Use repost whoami --json when the agent also needs the active organization, plan, usage, or identity for later decisions.
{
"schema": "repost.auth.status/v1",
"data": {
"authenticated": true,
"verified": true,
"method": "environment",
"status": {
"valid": true,
"token_id": "tok_01JZ8T7",
"name": "ci-agent-prod-read-write",
"type": "org",
"prefix": "rp_live_4f7",
"org_id": "org_01HV9S",
"scopes": ["read", "write"],
"created_at": "2026-06-01T10:12:00Z",
"expires_at": "2026-07-01T10:12:00Z"
}
}
}The method field is environment when REPOST_TOKEN is set and secure_storage otherwise. In this run the agent can perform read and write workflows, but it must not call --reveal-secrets, because secrets is absent from scopes.
This page owns the scope model. For how tokens are stored, the full lookup precedence, and config location, see Install & Auth in the CLI docs.
Cache identity for the run#
Fetch identity once at the start of the run and keep it in the agent process. There is no reason to re-check before every operation. Cache these fields and reuse them:
| Field | Use it for |
|---|---|
| Token ID and prefix | Audit logs and transcript summaries without exposing the full token. |
| Identity type | Branching between organization and user token behavior. |
| Scopes | Deciding whether a command should be attempted at all. |
| Active organization | Keeping bucket and forwarder operations in one workspace. |
| Plan and limits | Avoiding operations that will fail on quota or feature limits. |
Refresh identity only when a command returns unauthorized, active_org_required, forbidden_scope, or quota_exceeded, or when the workflow changes the token or organization.
Scope model#
Create the narrowest token that can complete the workflow.
| Scope | Grants | Keep out when |
|---|---|---|
| read | whoami, auth status, capabilities, docs, searches, events get/diff/schema, forwards search/chain, health, expect, tail, dlq list, replay status and listing. | The agent should not inspect production traffic. |
| write | Bucket and forwarder creation, pause/resume/disable, init, replay creation and replay actions, and generated artifacts. | The agent only needs diagnosis or reporting. |
| secrets | events get --reveal-secrets and events get --as-fixture only. Nothing else consults this scope. | Almost always. Prefer redacted output for agent transcripts. |
Do not grant secrets to make debugging convenient. It changes the behavior of exactly one command (events get); add it only for a workflow that explicitly needs unredacted values, and keep the transcript destination trusted. See Transcript safety.
Recover from auth errors#
Auth and context errors mean the current identity cannot run the command as-is. Branch on error.code, never the message.
unauthorized: the token is invalid or missing
The token is absent, malformed, expired, or revoked (HTTP 401). Replace REPOST_TOKEN with a freshly minted token and re-run repost auth status --json to confirm. Do not retry the failing command with the same token.
active_org_required: no unambiguous organization
A user token can see zero or multiple licensed organizations, so bucket and forwarder commands have no safe workspace target. Select one with repost config org set <slug> (persisted), pass --org <slug> per command, or set REPOST_ORG. Organization tokens remain the best fit for automation.
forbidden_scope: the token lacks a scope
The token is valid but missing a required scope (HTTP 403). forbidden_scope carries two fields you can act on directly:
repost replay evt_01JZ8V1 --bucket stripe-prod --forwarder prod-api --yes --jsonThe full envelope also carries message, hint, and docs. See the error contract.
Do not retry the same command with the same token.
Use error.missing_scope, which names precisely what to add, and mint a token at error.token_creation_url.
If escalation isn't possible, continue on a read-only path instead.
Request only the missing scope, not a broader token "to be safe."
Use in CI#
Store REPOST_TOKEN in your CI provider's secret store and export it only for the steps that need it. Because environment auth always wins, unset or shadow REPOST_TOKEN before testing a locally stored token.
For CLI token setup, see Install & Auth. For deploy gates, use repost forwarder pause and repost forwarder resume from the command reference.