Authentication and scopes

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

Verify 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"
    }
  }
}

{
  "schema": "repost.whoami/v1",
  "data": {
    "identity": {
      "token_id": "tok_01JZ8T7",
      "type": "org",
      "scopes": ["read", "write"]
    },
    "active_org_id": "org_01HV9S",
    "plan": { "plan": "scale", "has_hard_limits": true, "upgrade_url": "https://app.repost.sh/settings/billing" },
    "usage": { "events": 1249032, "events_limit": 5000000, "buckets": 8, "buckets_limit": 25 }
  }
}

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. Use an organization token for automation, or switch to a user context with exactly one licensed organization before retrying.

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

{
  "error": {
    "code": "forbidden_scope",
    "exit_code": 3,
    "missing_scope": "write",
    "token_creation_url": "https://app.repost.sh/settings/tokens"
  }
}

The full envelope also carries message, hint, and docs — see the error contract.

Stop the mutation

Do not retry the same command with the same token.

Request the exact scope

Use error.missing_scope — it names precisely what to add — and mint a token at error.token_creation_url.

Or downgrade

If escalation isn’t possible, continue on a read-only path instead.

Do not over-grant

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.

Continue

Output & errors

The error envelope, exit codes, and how to branch on error.code.

Transcript safety

What secrets scope exposes, and why redacted output is the default.

Discovery

Read the command manifest and per-command schemas.

Foundations

Playbooks

Operations

Authentication and scopes

Use environment auth

Cache identity for the run

Scope model

Recover from auth errors

Use in CI

Continue

Output & errors

Transcript safety

Discovery

​Use environment auth

​Cache identity for the run

​Scope model

​Recover from auth errors

​Use in CI

​Continue

Output & errors

Transcript safety

Discovery

Use environment auth

Cache identity for the run

Scope model

Recover from auth errors

Use in CI

Continue