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

# Create and Manage API Tokens for the Repost CLI and CI/CD

> Create personal or organization API tokens for CLI and automation access, set scopes and expiration, and revoke tokens that are no longer needed.

An API token authenticates CLI commands, scripts, and automation without an interactive browser session. You create a personal token for your own CLI access, or an organization token for automation that should belong to the workspace rather than an individual user account.

## Choose personal or organization scope

Token type determines ownership. Use the smallest owner boundary that fits the job.

<CardGroup cols={2}>
  <Card title="Personal token" icon="user-round">
    Use for your workstation and one-off CLI tasks. A personal token follows your user account and works across any licensed workspace you belong to.
  </Card>

  <Card title="Organization token" icon="building-2">
    Use for CI/CD pipelines, scheduled jobs, and shared automation. An organization token is scoped to the single workspace where you create it and keeps working even when teammates change roles or leave.
  </Card>
</CardGroup>

<Warning>
  Do not use a personal token for shared infrastructure. If the token owner loses their license, changes roles, or leaves the organization, automation using their personal token will stop working. Use an organization token so the credential belongs to the workspace, not the person.
</Warning>

## Create a token

Dashboard-created tokens require a name, one or more scopes, and an expiration date.

<Steps>
  <Step title="Open the token page">
    For a personal token, go to **Account Settings → Tokens**. For an organization token, go to **Organization → API Tokens**.
  </Step>

  <Step title="Name the token descriptively">
    Use a name that identifies the owner and workload — for example, `local-dev-zara`, `github-actions-prod`, or `nightly-replay-check`. A clear name makes the token table easier to audit later.
  </Step>

  <Step title="Choose scopes">
    Select at least one scope. **read** lets the token view buckets and forwarders. **write** lets the token manage forwarders, such as pausing, resuming, or disabling them.
  </Step>

  <Step title="Set an expiration">
    Choose **7 days**, **30 days**, **90 days**, **1 year**, or **Never**. The dialog defaults to **90 days**. Prefer a time-bounded expiration for anything used in automated workflows.
  </Step>

  <Step title="Copy the token immediately">
    The full token value is shown only once. Copy it to your password manager, keychain, or CI secret store before you close the dialog.
  </Step>
</Steps>

<Note>
  Repost stores a hash of your token and displays only the first 11 characters afterward — for example, `rp_12345678...`. The full token cannot be revealed once the creation dialog closes.
</Note>

## Token format

Every Repost API token starts with `rp_` and is exactly 43 characters long. The dashboard table shows only the first 11 characters so you can identify a token without exposing the secret value.

## Store your token securely

Keep the full token value in a secure location before closing the creation dialog.

<CardGroup cols={3}>
  <Card title="Password manager" icon="lock">
    Store the token in 1Password, Bitwarden, or your preferred password manager alongside a note describing the workload it authenticates.
  </Card>

  <Card title="System keychain" icon="key-round">
    Use macOS Keychain, GNOME Keyring, or an equivalent OS-level secret store for tokens on development machines.
  </Card>

  <Card title="CI secret store" icon="workflow">
    Add the token as an encrypted secret in GitHub Actions, GitLab CI, CircleCI, or whichever CI platform your pipeline runs on.
  </Card>
</CardGroup>

## Use tokens with the CLI

<Tabs>
  <Tab title="Store locally">
    Use `repost auth token` to save the token in the CLI's local credential store. Run `repost auth status` after storing it to confirm the token validates correctly with Repost.

    <CodeGroup>
      ```bash Argument theme={"languages":{"custom":["/languages/repost.json"]}}
      repost auth token rp_your_token_here
      ```

      ```bash Stdin theme={"languages":{"custom":["/languages/repost.json"]}}
      printf "%s\n" "$REPOST_TOKEN" | repost auth token
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Use in CI/CD">
    Set the `REPOST_TOKEN` environment variable in your job environment. Environment-variable authentication takes priority over any locally stored credentials.

    ```bash theme={"languages":{"custom":["/languages/repost.json"]}}
    export REPOST_TOKEN=rp_your_token_here
    repost auth status
    repost bucket list
    ```
  </Tab>
</Tabs>

<Tip>
  `REPOST_TOKEN` always overrides a stored token. When you need to test locally with a specific token, set the environment variable in your shell rather than re-running `repost auth token`.
</Tip>

## Read the token table

The token table is your inventory of all active and expired tokens for your account or organization.

| Column        | What it shows                                                                                                  |
| ------------- | -------------------------------------------------------------------------------------------------------------- |
| **Last used** | Displays `Today`, `Yesterday`, a relative age such as `3 days ago`, or `Never` if the token has not been used. |
| **Expires**   | Shows the expiration date, `Never`, or `Expired` when the token is past its expiration.                        |
| **Scopes**    | Shows the scopes assigned at creation time. Create a new token if the required scope set changes.              |

## Rotate a token

Rotate tokens on a schedule or any time you suspect a token has been exposed.

<Steps>
  <Step title="Create the replacement token first">
    Create the new token and add it to your CLI, CI secret store, or workload configuration before revoking the old one.
  </Step>

  <Step title="Verify the new token works">
    Run `repost auth status` or the command your automation depends on to confirm the new token authenticates correctly.
  </Step>

  <Step title="Revoke the old token">
    Open the token's actions menu and choose **Revoke token**. Any application still using the old token loses access immediately.
  </Step>
</Steps>

<Note>
  Revoked tokens are removed from the active token table. Expired tokens remain visible with an expired status until you revoke them manually.
</Note>

## Troubleshoot token failures

<AccordionGroup>
  <Accordion title="The CLI is still using an older token" icon="terminal">
    `REPOST_TOKEN` overrides locally stored credentials. If you set this environment variable and then ran `repost auth token` to store a different token, the environment variable still wins. Clear `REPOST_TOKEN` from your shell to use the stored credential.
  </Accordion>

  <Accordion title="Logout doesn't clear REPOST_TOKEN" icon="log-out">
    `repost auth logout` removes locally stored credentials. It does not unset the `REPOST_TOKEN` environment variable in your shell or CI job. Later commands continue to prefer the environment value while it exists.
  </Accordion>

  <Accordion title="The token is expired" icon="calendar-x">
    Create a replacement token and update the workload. Expired tokens fail validation and remain visible in the table with an expired status until you revoke them.
  </Accordion>

  <Accordion title="The token was revoked" icon="ban">
    Revocation is immediate and permanent. Revoked tokens are removed from the active token table and fail all future validation requests.
  </Accordion>

  <Accordion title="The automation is in the wrong workspace" icon="building-2">
    Organization tokens are scoped to a single workspace. If the token was created in workspace A, CLI commands targeting workspace B will fail. Create the token from the workspace that owns the buckets and forwarders your job needs.
  </Accordion>

  <Accordion title="A personal token sees fewer resources than expected" icon="user-round-x">
    Personal tokens inherit the permissions of the token owner. If you are not licensed in a particular workspace, CLI commands targeting that workspace will fail until an owner or admin assigns you a seat.
  </Accordion>
</AccordionGroup>