Skip to content
Scalpels home

Scalpels is officially launching on October 31, 2026. Special early adopter pricing is available now.

← All documentation

Documentation

Crate

Credentials

Updated

Every request for /packages.json, /p2/... or /dist/... must carry a registry credential. Composer sends it as HTTP Basic auth: the username can be anything (Crate's tools use token) and the password is the credential.

What a registry credential can do

A registry credential is a Basic credential with the purpose crate.composer.consume. That purpose lets it download Composer metadata and archives, and nothing else. It cannot add or remove repositories, read source tokens or manage credentials.

One active registry credential can read every package your Crate serves. There is no way to limit a credential to some packages.

Crate answers every request without a valid registry credential with the same 401 and a WWW-Authenticate: Basic realm="Crate" header, whether the credential is missing, malformed, for another purpose, not Basic, expired, revoked, or belongs to a removed account. It never says which.

Personal and installation credentials

You issue both kinds from Settings after signing in. Owners, Admins and Members can all issue them.

  • Personal credentials belong to you. They keep working only while your account is active and allowed to use Crate, so they stop working when you are deactivated. Use them on your own machine.
  • Installation credentials belong to the Crate deployment rather than to a person, and keep working when the person who issued them leaves. Use them for servers, CI and other applications. Each one carries a subject reference, a label for the automation that uses it, such as billing-worker.

When Scalpels attaches one of your applications to Crate, it issues the credential for you and writes it straight into that application's environment. See Connecting your apps.

Issue a credential

  1. Open Settings → Personal credentials or Settings → Installation credentials.
  2. Under Issue a credential, choose crate.composer.consume / basic.
  3. Enter a name. For an installation credential, also enter the subject reference.
  4. Select Issue.

Crate shows Save this credential now with the username and password. This is the only time the password is shown. Put it directly into the secret store, environment variable or auth.json that needs it; do not paste it into chat, commits or logs.

Rotate and revoke

Each credential in the list has Rotate and Revoke buttons.

  • Rotate issues a replacement and shows its password once. Update everything that uses the old one.
  • Revoke stops the credential working immediately. Composer then gets a 401 from Crate.

Names are labels only. Two credentials can share a name; Crate tells them apart by ID.

Issuing credentials from your own application

The artisan-build/crate-client package includes CrateIssuer, a small client for Crate's /bfc/credentials API. An application of yours can use it to issue, list, rotate and revoke installation credentials, for example to hand a credential to each customer who buys access to your packages. It needs an operator credential for your Crate with the matching credential:mint, credential:read, credential:rotate and credential:revoke abilities, set as CRATE_SERVICE_TOKEN in that application.

The full reference is the integration guide in the Crate repository.