Access and permissions

Everything in the Dependency Firewall happens inside a namespace, and every actor in it, a person or a system, acts through a set of permissions. This page explains how that set is computed. For the day-to-day tasks, see Manage access and Manage tokens.

Namespaces, teams, grants, and tokens

• Namespace. The isolation boundary. Users, teams, tokens, and firewalls all live in one namespace; the namespace is part of every URL.
• Teams. Users belong to teams; teams carry namespace-level permissions. Two protected teams always exist: everybody (all users; namespace access, PAT creation, firewall creation and read) and admin (adds team management, SAT creation, and full firewall write).
• Per-firewall grants. Each firewall's configuration maps teams to permissions on that firewall. New firewalls grant read (fw:access, fw:clone, fw:read) to everybody and everything to the creating team.
• Tokens. Requests authenticate with a token, and the token can carry its own restrictions.

Permissions are verbs, not roles: fw:update:rule, ns:create:pat, team:update:membership. The full catalog is in the permissions reference.

How a user's effective permissions are computed

For a user acting on a firewall, three layers intersect:

Additive within a layer, restrictive across layers: more teams never reduce access, but every layer must allow an action for it to be permitted. A firewall grant means nothing to a user whose teams lack the namespace-level permission, and a token scoped to fw:access cannot update rules regardless of how privileged its owner is.

Person tokens and system tokens

The two token types resolve permissions differently:

• Personal Access Tokens (PAT) act as the user. Permissions are computed from team memberships as above, then narrowed by any restrictions on the token. A PAT is never more powerful than its owner, and revoking team membership immediately affects existing tokens.
• Service Access Tokens (SAT) are self-contained. They belong to the namespace, not a user, and carry their permissions explicitly. A fixed catalog caps what a SAT can ever hold: access, read, clone, and configuration/rule/exception updates, but not team management, credential updates, or namespace and firewall deletion. Those actions require a person.

Both types can be restricted to specific firewalls, and both expire.

Trusted Builder tokens are SATs minted through an OpenID Connect exchange with a 15-minute lifetime; the same rules apply, only the issuance differs. See Access Tokens.

Consequences

• To give one person more access, use a team. There are no per-user grants; a team with one member is the intended pattern.
• Read access is namespace-wide by default. Everybody can see every firewall's configuration unless a firewall's grants say otherwise; write access is what teams gate.
• Scoped tokens are the cheap safety win. A CI token with fw:access restricted to one firewall leaks far less than it could; see Manage tokens.

Related

• How-to: Manage access, Manage tokens
• Reference: Permissions, Tokens
• Getting started: Access Tokens