Tokens

Token types, prefixes, lifetimes, scope claims, the interaction ID suffix, and the credential envelope format.

Reference for the token formats and rules. For which token to use where, see Access Tokens; for workflows, see Manage tokens.

Types

Type	Prefix	Bound to	Created via	Permission required
Personal Access Token (PAT)	`pat-`	A user	Dashboard / API	`ns:create:pat`
Service Access Token (SAT)	`sat-`	The namespace	Dashboard / API	`ns:create:service-token`
Trusted Builder token	`sat-`	A CI workflow identity	OIDC exchange	Registered Trusted Builder

Tokens are opaque: a prefix plus a random UUID. The server stores only a hash; the value is shown once at creation and cannot be recovered.

A Trusted Builder token is a SAT minted through an OpenID Connect (OIDC) exchange instead of created directly; see Trusted Builders for setup.

Lifetime

Path	Default	Maximum
API (`validForHours`)	12 hours	2 years
Dashboard presets	7 days	1 year (presets: 1, 7, 30, 90, 365 days)
Trusted Builder exchange	15 minutes	15 minutes

Expiry is checked on every request. Deleting a token has the same immediate effect.

Permissions

Token permissions are selected when the token is created. They cannot be changed later; create a new token and delete the old one to change scope.

Token	Create permission	Permission behavior
PAT	`ns:create:pat`	Acts as the user, narrowed to the selected permissions and firewall IDs
SAT	`ns:create:service-token`	Acts as the namespace, with only the selected permissions and firewall IDs
Trusted Builder token	Registered Trusted Builder	Uses the Trusted Builder registration permissions and firewall IDs

The server rejects token creation when the requested permissions are broader than the creator's own permissions. If the creator is already using a firewall-restricted token, the new token cannot include firewalls outside that restriction.

SATs can carry at most the Service Access Token permission catalog. SATs cannot manage upstream credentials, teams, token creation, token deletion, namespace deletion, or firewall deletion.

Scope claims

A token can carry two optional restrictions, set at creation and immutable afterwards:

Claim	Effect
`permissions`	The token acts with at most these permissions. For PATs this narrows the user's team permissions; for SATs it is the token's entire permission set, capped by the SAT catalog
`firewalls`	The token works only on the listed firewalls

Wire format

The token goes in the Authorization header, either directly or as basic auth (the password is used as the token; the username if the password is empty):

Authorization: Bearer pat-3f2a...
Authorization: Basic base64(anything:pat-3f2a...)

NuGet clients may send X-NuGet-ApiKey instead; the firewall accepts it equivalently on NuGet routes.

Interaction ID suffix

Any token may carry an opaque correlation ID after a double colon:

pat-3f2a...::build-4711

The firewall strips the suffix before validating and records it on every log entry from that request. :: never occurs in token values, so the split is unambiguous.

Credential envelope

For just-in-time upstream credentials, a token can be wrapped in an envelope: env- followed by base64 (RawURL) JSON bundling the real token and per-upstream credentials:

{
  "tkn": "sat-9c41...",
  "crd": { "e2de947a": { "token": "<upstream token>" } }
}

The envelope replaces the token in the Authorization header. The interaction ID suffix stays outside the envelope (env-...::build-4711). Maximum encoded size is 64 KiB. See bsfw config credentials.

Validation summary

A request is rejected when the token is unknown, expired, deleted, or used outside its namespace; when a firewalls claim does not list the target firewall; or when the action needs a permission the token does not carry. Failed attempts are recorded in the audit log with a non-reversible token identifier, so repeated failures are correlatable without exposing token material.

Getting started: Access Tokens
How-to: Manage tokens
Concept: Access and permissions
Reference: Permissions, CLI

Tokens

On this page