Skip to content

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.

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.

A binding holds one of:

  • a tier: viewer, developer or admin, with the actions that tier has in the Organization;
  • a custom role of the Organization (role_id);
  • a list of actions (capabilities), for example only environment: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.

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 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.

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.

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.

Terminal window
canopy access grant --group payments --project fleet-api --role developer
canopy access list --group payments
canopy access explain --project fleet-api --action environment:deploy
canopy access owners fleet --role developer --scope environments
canopy access review --days 30
canopy access revoke <binding_id>

See the CLI reference for every canopy access command.

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 why
await sdk.access.grantOwners(systemId, { role: 'developer', scope: 'environments' }); // {created, updated, kept}
await sdk.access.divergences(teamId, { days: 30 }); // what turning enforcement on would have changed
await sdk.access.revoke(teamId, bindingId);
GET /teams/{team_id}/access?project_id=&environment_id=&group_id=&user_id=
POST /teams/{team_id}/access
DELETE /teams/{team_id}/access/{binding_id}
GET /teams/{team_id}/access/divergences?days=
GET /groups/{group_id}/bindings
POST /systems/{system_id}/owner-access
GET /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.

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.