Access model
Access comes from organization and project grants; tokens restrict those rights further, and package visibility applies to every install.
| Actor | Organization reads | Organization writes | Project reads and installs | Project writes |
|---|---|---|---|---|
| User with a session | The user's organization grants. | The user's organization grants, with session and mutation checks. | The union of project grants and inherited organization project:* permissions; package visibility still applies. | The same union permits settings, grants, package management and publishing, sources, service principals and tokens as granted; publishing requires project:packages:write. |
| User with a personal access token (PAT) | Live organization grants, only with all project mode and full scope; session-only actions excluded. | Only token-eligible actions allowed by those grants and scope. | Live project grants and inherited organization project:* permissions, restricted by token scope, selected/all project binding and project token cap; package visibility applies. | Only token-eligible writes, including publishing with project:packages:write, within those restrictions. Fresh PAT validation evidence is required for every operation. |
| SSO group member | A matching organization group grant contributes its role, with fresh membership and provider identity evidence. | Only actions in that role, with fresh membership and provider identity evidence. | Matching project group grants and inherited organization project:* group permissions, with fresh membership and provider identity evidence; package visibility applies. | Only actions in those roles, with fresh membership and provider identity evidence. Session or token restrictions also apply. |
| Service principal using a service token | Stored organization permissions, restricted by token scope and binding. | No session-only actions. | Stored project permissions, restricted by token scope, project binding and project token cap; package visibility still applies. | Only token-eligible package writes within those restrictions. |
| Customer token | None. | None. | None: the prefix is reserved and authentication refuses it. | None. |
An organization grant and a project grant have different boundaries. An organization role can carry project:* permissions inherited by projects; a project grant does not grant organization administration. A token narrows the principal's rights; it cannot create rights the principal lacks.
Roles and grants
These are the built-in role keys and their shipped names. Inspect custom role permissions before treating a custom role as equivalent.
| Role key | Shipped name | Rights |
|---|---|---|
organization_admin | Organization Admin | org:read, org:settings:write, org:users:read, org:users:write, org:roles:read, org:roles:write, org:grants:read, org:grants:write, org:projects:create, org:projects:archive, org:sources:read, org:sources:write, org:tokens:read, org:tokens:revoke, org:service-principals:write, org:packages:manage, org:import:write, org:import:approve, org:audit:read, project:read, project:settings:write, project:grants:read, project:grants:write, project:packages:read, project:packages:write, project:packages:manage, project:sources:read, project:sources:write, project:service-principals:write, project:tokens:create, project:tokens:read, project:tokens:revoke, project:audit:read. |
organization_auditor | Organization Auditor | org:read, org:users:read, org:roles:read, org:grants:read, org:sources:read, org:tokens:read, org:audit:read, project:read, project:grants:read, project:packages:read, project:sources:read, project:tokens:read, project:audit:read. |
project_owner | Project Owner | project:read, project:settings:write, project:grants:read, project:grants:write, project:packages:read, project:packages:write, project:packages:manage, project:sources:read, project:sources:write, project:service-principals:write, project:tokens:create, project:tokens:read, project:tokens:revoke, project:audit:read. |
project_developer | Project Developer | project:read, project:packages:read, project:packages:write, project:sources:read, project:tokens:create. |
project_auditor | Project Auditor | project:read, project:grants:read, project:packages:read, project:sources:read, project:tokens:read, project:audit:read. |
Group grants match both the provider and group name. Membership evidence and the matching identity's validation evidence expire after 24 h; signing in refreshes evidence through the configured identity provider. A group name by itself does not grant access.
Token kinds
This is the shared token-kind table for client setup and CI recipes. Prefixes identify kinds; they are not usable credentials.
| Kind and prefix | Scope and binding | Default lifetime | Revocation and loss of access |
|---|---|---|---|
Personal access token (PAT), pb_pat_ | read, write or full; selected projects or all projects the user can access. Live user grants and each project's token cap apply. | 90 days initially, shortened by a lower configured maximum. tokens.maxLifetimeDays.personal: 1–365 days, default maximum 365 days. PAT validation evidence expires after 24 h, independently of token expiry. | The user can revoke their own PAT; a session with org:tokens:revoke can revoke it. Revoked, expired or inactive-principal tokens fail authentication; stale PAT validation also denies use. |
Service token, pb_svc_ | read, write or full; a project-bound or organization service principal with stored permissions. The issuer must hold every permission conferred by the token. | 90 days initially, shortened by a lower configured maximum. tokens.maxLifetimeDays.service: 1–3,650 days, default maximum 365 days. | A session with org:tokens:revoke can revoke it; a session with project:tokens:revoke can revoke a service token bound to that project. Revocation, expiry or an inactive principal denies use. |
Customer token, pb_cst_ | Reserved; no accepted scope or binding. | No issuance or default lifetime. | Authentication refuses the reserved kind. |
| Scope | Allowed operations, subject to principal rights and project policy |
|---|---|
read | Read project details and packages. |
write | read plus publish packages. |
full | All token-eligible operations. Session-only actions still require a user session. |
Only an all project-mode token with full scope can exercise organization permissions. A selected PAT binds 1 to 200 distinct projects; an all-project PAT follows the user's current and future project access. Issuing a PAT requires fresh reauthentication.
Issuing or rotating a project service token requires project:tokens:create; an organization service token requires org:service-principals:write and organization admin authority. Both require fresh reauthentication, and the issuer must hold all permissions the token confers. Listing tokens requires project:tokens:read or org:tokens:read at the corresponding boundary.
Token use checks revocation and expiry on each authentication. Revoking a token stops its subsequent use; it does not revoke another token or undo an archive already downloaded. Token revocation requires a user session.
Project package visibility and source credentials
Installing requires both the right to read packages in the requested project and a package visible in that project. Credentials used to read a vendor source do not grant a developer or token access to the project.
| Rule | Effect |
|---|---|
| Project-owned source | Serves only its owner project in the same organization, including when an attachment to another project is present. |
| Organization-owned source | May serve attached projects. It is unsuitable for credentials that must belong to only one project. |
| Attached source and package selection | Visibility comes from an explicit package selection or the attached source's include/exclude patterns and package visibility flag. An explicit selection takes priority over pattern filtering. |
| Inactive project | Has no winning package. |
| Public proxy | Cannot supply a name held by a non-proxy source in the organization or matching a registered name, even if the private package is invisible to the caller. |
| Metadata cache | Keys include the project, source, package revision and organization scope; cache fills validate the live visibility epoch. A cached document does not grant another project access. |
| Vendor credential | Must belong to the same organization and project as its source. Separate project sources can use different vendor credentials for the same repository URL. |
An authenticated actor outside a project's visibility receives 404; an actor who can see the project but lacks the required operation can receive 403. At the package boundary, an absent or invisible package receives 404.
Worked examples
Agency with three clients
Create projects client-a, client-b and client-c. Grant each project's SSO group the project developer role only in that project. Put each client's vendor credentials in a source owned by that client's project and attach that source only there. A developer in the first group cannot reach another project's source by guessing a package name or archive URL.
Who can install: members of each project's group with fresh evidence and a usable session or package-reading token can install that project's visible packages. Organization admins and auditors also inherit package-read rights across projects; use group grants to separate project users, not to hide packages from organization administrators.
Internal-only package
Keep example/internal-tools in a source owned by project internal. Grant the internal engineering group the project auditor role if it only installs packages. Do not grant an external group access to internal. The source ownership rule keeps that package outside other projects.
Who can install: the internal group and organization roles inheriting package-read rights, with usable credentials. A token bound only to a different project cannot install from internal.
Customer-facing token
Customer tokens cannot authenticate or enforce a customer cut-off. The parser recognizes the customer prefix, but the authentication gate rejects it. A service token has no customer cut-off semantics.
Who can install: nobody using a customer token. A separately issued service token can install only within its stored permissions, binding and scope, without a customer cut-off.
What is not enforced
The organization setting token_ci_readonly_expiry_days is not enforced by service tokens today; the service-token ceiling documented above comes from the code’s tokens.maxLifetimeDays.service policy.
Customer-token access and customer cut-offs are not implemented in the authentication path. Identity evidence expiry is enforced locally, but this does not establish a universal delay for detecting removal at an identity provider: the broker does not perform unattended daily identity-provider revalidation. Sign in again when PAT evidence becomes stale.
For project-owned vendor credentials, use Vendor repositories as sources. For client configuration, see Composer and npm, pnpm and yarn.