Authentication & Tokens

Every request to the vlt registry is authenticated with a bearer token, apart from the endpoints used by the login flow itself. Tokens belong to an account — one token works for both of the account’s registries (main and npm).

Log in from the CLI

The registry supports the npm web login flow. Point your client at your registry and log in:

Terminal

$ vlt login --registry=https://registry.vlt.io/acme/main/

Your browser opens vlt.io to confirm the login, and the client stores the resulting token in the vlt keychain. npm works the same way:

Terminal

$ npm login --auth-type=web --registry=https://registry.vlt.io/acme/main/

See Authentication for everything the vlt client supports around credential storage and identities.

Personal and service tokens

There are two kinds of tokens:

• Personal tokens are bound to your user. Writes made with a personal token are subject to the account’s two-factor (OTP) requirement. Logging in from the CLI mints a personal token scoped to package:read and package:write.
• Service tokens belong to the account rather than a person. They are meant for CI and automation, and they are not subject to OTP prompts. Creating service tokens requires an owner or admin role.

Tokens start with the vlt_1_ prefix. The registry stores only a hash of each token, so the full value is shown once at creation — copy it then.

Privileges and expiry

Every token carries a set of privileges, such as package:read, package:write, token:read, or member:write. A request succeeds only if both the token and the requesting user’s account role grant the privilege, so a read-only token stays read-only no matter who uses it, and a token can never grant more than its creator’s own role allows.

For example, a CI token that only installs packages needs just package:read; a publish token needs package:write as well.

Tokens can optionally be given an expiration date, after which they stop working. Expired and revoked tokens are rejected on every request.

Managing tokens

Create, inspect, and revoke tokens from your account’s token settings in the dashboard. Members can create and revoke their own personal tokens; owners and admins can also manage service tokens.

Note

The dashboard is the easiest place to manage tokens, but the npm token subcommands (npm token list, npm token create) also work against your registry. pnpm token does not — pnpm reports Not implemented in pnpm. Use the npm CLI directly.

Using tokens in CI

Provide a token through the environment rather than a config file. The portable form is VLT_TOKEN alongside VLT_REGISTRY:

Terminal

VLT_REGISTRY=https://registry.vlt.io/acme/main/ VLT_TOKEN="<service token>" vlt install

Per-registry VLT_TOKEN_* variables, named after the registry URL with non-alphanumeric characters replaced by _, also work:

Terminal

VLT_TOKEN_https_registry_vlt_io_acme_main="<service token>" vlt install

Caution

The per-registry variables do not apply to registries configured through scoped-registries — vlt sends no credentials to a scoped registry on their strength alone. If you use scoped-registries, set VLT_TOKEN and VLT_REGISTRY instead.

See Authentication — CI for details, and CI & automation for the publish workflow.

With npm, use the standard .npmrc auth entry, ideally referencing an environment variable:

.npmrc

@acme:registry=https://registry.vlt.io/acme/main/
//registry.vlt.io/acme/main/:_authToken=${NPM_TOKEN}

Removing credentials

• vlt logout --registry=... removes the token from your keychain. Revoke the token itself in the dashboard.
• vlt token rm removes a token from your local keychain only.
• Revoking a token in the dashboard invalidates it everywhere, immediately.