Skip to content
Crate HavenHaven docs

Tokens & access

Humans use sessions; machines use tokens. A token is shown once at mint time, stored hashed, and can be revoked at any time. Every mint and revocation is audited.

Scopes

Section titled “Scopes”

Full (organization token): acts with the organization’s whole entitlement, including publishing. Use it for release pipelines. Full tokens do not expire; they live until revoked.

Namespace read: reads only the namespaces it names. This is the least-privilege credential for CI and for customers; it cannot publish, cannot touch settings, and stays useful even if pointed at a private namespace. Namespace read tokens expire after a year.

  • The any-version flag: a namespace read token can optionally see held versions too, bypassing the policy gate for reads. This exists for pre-promotion testing pipelines. It is deliberately loud: the flag is recorded at mint time and marked in every token listing. Do not use it for normal consumption; it defeats the gate.

Personal public-read: minted by any user from their own account, reads promoted versions of every public namespace on the instance. Capped at 5 active tokens per user, expires after a year. This is the token you put on a laptop to consume public crates.

Minting

Section titled “Minting”
  • Organization tokens (full or namespace read): the organization’s Tokens page. Mixing is prevented: a namespace read token cannot carry admin rights, and the any-version flag requires named namespaces.
  • Personal public-read tokens: your account page.

Give every token a name that says where it lives (“ci-deploy”, “laptop”). Revocation is immediate.

Using a token with cargo

Section titled “Using a token with cargo”
Terminal window
cargo login --registry acme

or in CI:

Terminal window
export CARGO_REGISTRIES_ACME_TOKEN="haven_..."

with global-credential-providers = ["cargo:token"] in the cargo config (see Getting started).

Tokens versus grants

Section titled “Tokens versus grants”

A token authenticates; entitlement decides what it can read. An organization’s tokens read the organization’s namespaces. To read another organization’s private crate you need a grant naming your identity; your existing token then works. Withdrawing the grant cuts off access without anyone rotating tokens.