> ## Documentation Index
> Fetch the complete documentation index at: https://docs.repost.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and scopes

> Authenticate agents with scoped tokens, cache identity once, and recover from missing-scope errors.

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

```bash theme={null}
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.

<CodeGroup>
  ```json auth status theme={null}
  {
    "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"
      }
    }
  }
  ```

  ```json whoami theme={null}
  {
    "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 }
    }
  }
  ```
</CodeGroup>

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

<Note>
  This page owns the **scope** model. For how tokens are stored, the full lookup precedence, and config location, see [Install & Auth](/cli/install-auth#credential-priority) in the CLI docs.
</Note>

## 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                                                |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| <Badge>read</Badge>    | `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.             |
| <Badge>write</Badge>   | Bucket and forwarder creation, pause/resume/disable, `init`, replay creation and replay actions, and generated artifacts.                                                              | The agent only needs diagnosis or reporting.                 |
| <Badge>secrets</Badge> | `events get --reveal-secrets` and `events get --as-fixture` only — nothing else consults this scope.                                                                                   | Almost always. Prefer redacted output for agent transcripts. |

<Warning>
  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](/agents/transcript-safety).
</Warning>

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

<AccordionGroup>
  <Accordion title="unauthorized — the token is invalid or missing" icon="circle-x">
    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.
  </Accordion>

  <Accordion title="active_org_required — no unambiguous organization" icon="building-2">
    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.
  </Accordion>

  <Accordion title="forbidden_scope — the token lacks a scope" icon="key-round">
    The token is valid but missing a required scope (HTTP 403). `forbidden_scope` carries two fields you can act on directly:

    <CodeGroup>
      ```bash Command theme={null}
      repost replay evt_01JZ8V1 --bucket stripe-prod --forwarder prod-api --yes --json
      ```

      ```json Error (stderr, exit 3) theme={null}
      {
        "error": {
          "code": "forbidden_scope",
          "exit_code": 3,
          "missing_scope": "write",
          "token_creation_url": "https://app.repost.sh/settings/tokens"
        }
      }
      ```
    </CodeGroup>

    The full envelope also carries `message`, `hint`, and `docs` — see [the error contract](/agents/output-and-errors#handle-errors).

    <Steps>
      <Step title="Stop the mutation">
        Do not retry the same command with the same token.
      </Step>

      <Step title="Request the exact scope">
        Use `error.missing_scope` — it names precisely what to add — and mint a token at `error.token_creation_url`.
      </Step>

      <Step title="Or downgrade">
        If escalation isn't possible, continue on a read-only path instead.
      </Step>

      <Step title="Do not over-grant">
        Request only the missing scope, not a broader token "to be safe."
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## 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](/cli/install-auth#credential-priority). For deploy gates, use `repost forwarder pause` and `repost forwarder resume` from the [command reference](/cli/reference#forwarder).

## Continue

<Columns cols={3} className="gap-y-4">
  <Card title="Output & errors" icon="braces" href="/agents/output-and-errors" cta="Read the contract" arrow="true">
    The error envelope, exit codes, and how to branch on `error.code`.
  </Card>

  <Card title="Transcript safety" icon="file-lock-2" href="/agents/transcript-safety" cta="Avoid leaks" arrow="true">
    What `secrets` scope exposes, and why redacted output is the default.
  </Card>

  <Card title="Discovery" icon="compass" href="/agents/discovery" cta="Learn the surface" arrow="true">
    Read the command manifest and per-command schemas.
  </Card>
</Columns>