Access
An Organization role (viewer, developer, admin, or a custom role) says what a person may do everywhere in the Organization. An access binding adds to it for part of the Organization: a person or a group holds a role on the whole Organization, on one project or on one environment. Bindings only add. They never take away something a person’s Organization role already allows.
How a decision is made
Section titled “How a decision is made”For an action on an environment, Canopy looks at what the person holds on that environment, on its project and on the Organization, and allows the action if any of them does. What a person holds is their Organization role, the bindings made for them, and the bindings of every group they are in and of the groups above those.
A role given on a project or an environment only reaches what is about that place. It applies wherever Canopy checks that place: the API, opening a shell in an environment, the deploy gates of a pipeline, approvals, Blueprint apply and the package and image registries of the Organization. It never gives the actions that belong to the Organization (managing members, roles, groups or billing), and on an environment it leaves out the actions that are about creating or deleting projects. A role given on the Organization is the same as having it as the Organization role.
Roles and actions
Section titled “Roles and actions”A binding holds one of:
- a tier:
viewer,developeroradmin, with the actions that tier has in the Organization; - a custom role of the Organization (
role_id); - a list of actions (
capabilities), for example onlyenvironment:approve_deploy.
Giving the same person or group another role in the same place replaces the first. A binding can end on a date
(expires_at, at most ten years ahead); an ended binding gives nothing and is not listed. An Organization holds up to
1000 bindings.
Who can give access
Section titled “Who can give access”You need access:manage on the place you give it, which the admin tier has, and you can only give actions you hold
yourself there. You cannot give yourself access, and a group’s maintainer who adds a member to a group that carries
bindings must hold all of what those bindings give, without counting what they hold only through that same group.
Removing a group, or a person leaving the Organization, removes their bindings.
| Action | Needs |
|---|---|
| See the bindings of a group | Any member of the Organization |
| See the bindings of an Organization, a project or an environment | access:manage there |
| Give or remove a binding | access:manage there, and holding what you give |
Owning a System
Section titled “Owning a System”Owning a System grants no access. Instead, you can give the owning groups a role on the System’s environments, or on the projects they belong to, in one step. Each of these is an ordinary binding with a note that it came from the System, so you can change or remove it one by one. A binding someone made by hand is left as it was.
Switching it on
Section titled “Switching it on”The platform feature host.group_access decides whether bindings are enforced. While it is off, bindings can be
recorded and listed but change nothing, and a request that a binding would have allowed and the Organization role
refused is logged as an authz.divergence event. Review sums those up for the last 1 to 90 days: how many there were,
which actions and which people, the latest ones, and whether every one is explained by a binding. When none is
unexplained, turning the feature on changes only what the bindings give. Once it is on, they allow what they give.
In the app
Section titled “In the app”On a group’s page under Settings → Organization → Groups, Access lists what the group holds and, with
access:manage, gives it a role on the Organization or a project and removes it. A System’s Owners and watchers
section has Give owning groups access.
From the CLI
Section titled “From the CLI”canopy access grant --group payments --project fleet-api --role developercanopy access list --group paymentscanopy access explain --project fleet-api --action environment:deploycanopy access owners fleet --role developer --scope environmentscanopy access review --days 30canopy access revoke <binding_id>See the CLI reference for every canopy access command.
From the SDK
Section titled “From the SDK”await sdk.access.grant(teamId, { groupId, projectId, role: 'developer' });await sdk.access.list(teamId, { projectId }); // {enforced, bindings}await sdk.access.forGroup(groupId);await sdk.access.explain(teamId, { projectId }); // what you can do there, and whyawait sdk.access.grantOwners(systemId, { role: 'developer', scope: 'environments' }); // {created, updated, kept}await sdk.access.divergences(teamId, { days: 30 }); // what turning enforcement on would have changedawait sdk.access.revoke(teamId, bindingId);From the API
Section titled “From the API”GET /teams/{team_id}/access?project_id=&environment_id=&group_id=&user_id=POST /teams/{team_id}/accessDELETE /teams/{team_id}/access/{binding_id}GET /teams/{team_id}/access/divergences?days=GET /groups/{group_id}/bindingsPOST /systems/{system_id}/owner-accessGET /teams/{team_id}/me/permissions?project_id=&environment_id=POST /teams/{team_id}/access takes user_id or group_id, optionally project_id or environment_id (neither means
the whole Organization), one of role, role_id and capabilities, and optionally expires_at. POST /systems/{system_id}/owner-access takes { "role": "viewer" | "developer" | "admin", "scope": "environments" | "projects" }. GET .../me/permissions with a project or an environment lists what you can do there and, for each
action, the role or binding that allows it.
GET /teams/{team_id}/access/divergences needs access:manage and returns mode, total, explained, unexplained,
ready, by_action, by_person and the recent events.
Creating, changing and removing a binding is recorded in the Organization’s audit log as access.binding_created,
access.binding_updated and access.binding_removed.
The member role
Section titled “The member role”member is an Organization role below viewer. A member sees the directory (who is in the Organization and its
groups) and nothing else by default. What else they see comes from bindings given to them or to a group they belong to:
a binding that gives environment:read on a project shows that project and its environments; on an environment, that
environment and its project; on the whole Organization, everything, as a viewer sees it. A System shows only when one of
its environments is visible, and then lists only the environments the person can see. A project or environment the
person cannot see answers 404, as if it did not exist.
This reaches the project, environment and System lists and reads, the Organization’s Activity feed (limited to the environments they can read), the account data export, new notifications, the graph and the assistant’s context. The graph and the assistant give a member the projects and environments they can read and the builds, releases and other nodes that belong to one of them; a node that belongs to neither (a repository, for example) stays out of reach until a binding on the whole Organization is given.
GET /teams/{team_id}/me/visibility says what the caller can see: the projects, environments and Systems their bindings
reach, and counts of the rest (never names). For anyone who is not a member it answers restricted: false. The CLI has
canopy teams visibility <team_id> and the SDK teams.meVisibility().
Notifications are filtered when they are read, so a binding that is taken away hides what it let through. Notifications sent before 2026-11-11 are matched to their environment by the event that caused them.
Giving the member role (PATCH /teams/{team_id}/members/{user_id}, an invite, or an SSO default or group mapping) needs
the host.read_scoping platform feature; a person who already is a member stays scoped when the feature is off.