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

Full (organization token): acts with the organization’s whole entitlement, including publishing. Full tokens do not expire; they live until revoked. A release pipeline can skip storing one: trusted publishing mints a 30-minute capability token from the CI job’s own OIDC identity.

Capabilities (organization token): a write credential narrower than full. It carries an explicit set of capabilities and performs nothing outside it:

• publish: publish versions of existing packages. Creating a new package name additionally requires the token’s subject to be a registry owner, so this capability alone can never claim names.
• yank: yank and unyank versions.
• annotate: the maintainer surfaces: publisher vouches, state trusts, hold acceptances, facts, file licenses, SBOMs, docs uploads, and attestations.
• manage: the registry-owner levers: settings, policy, owner sets, grants, promotions and blocks, mirror configuration.

A capability token can name registries, or name none and cover every registry of its organization, present and future. It reads like a registry read token over the same reach, is never an admin credential, and what it may do is always the intersection with what its subject’s ownerships allow: a capability narrows a credential, it never grants ownership. Capability tokens expire after a year.

Registry read: reads only the registries it names. This is the least-privilege credential for consumers; it cannot publish, cannot touch settings, and stays useful even if pointed at a private registry. Registry read tokens expire after a year.

• The any-version flag: a registry 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.
• Narrowing to packages and versions: a registry read token can name packages and version ranges instead of reaching everything in its registries. This is the credential you hand a customer who bought one package at one range: mint some-crate at ^1, and when they buy the next major, mint a token carrying both. Anything outside the list answers as if it did not exist, so the token never reveals what else the registry holds. Every registry the token names needs at least one package, or the mint is refused rather than quietly leaving that registry wide open. On a static file registry, a range narrower than * needs the package to declare the semver version scheme first.

Personal public-read: minted by any user from their own account, reads promoted versions of every public registry 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

• Organization tokens (full, capabilities, or registry read): the organization’s Tokens page. Mixing is prevented: neither a capability token nor a registry read token can carry admin rights, the any-version flag belongs to read tokens only, and a capability token must check at least one capability.
• 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

cargo login --registry acme

or in CI:

export CARGO_REGISTRIES_ACME_TOKEN="haven_..."

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

On a static file registry there is no cargo config; the same token rides in the request header:

curl -H "Authorization: Bearer haven_..." ...

Tokens versus grants

A token authenticates; entitlement decides what it can read. An organization’s tokens read the organization’s registries. To read another organization’s private package you need a grant naming your identity; your existing token then works. Withdrawing the grant cuts off access on the very next request, without anyone rotating tokens, and both the grant and the withdrawal are on the audit record.

Selling access to a customer therefore has two shapes. Grant their identity, and their own token reaches what you granted. Or mint a read token narrowed to the package and range they bought and hand them the secret, which needs nothing on their side at all. A grant never widens a token that is already narrower: the scope is always the tighter of the two.