Your permissions
Roles decide what someone can do on a team: the built-in tiers (member, viewer, developer, admin, owner), optionally
widened by a named custom role. Every API route enforces this on its own. A client that wants to show an action as
disabled, with the reason, can ask first:
GET /teams/{team_id}/me/permissionsGET /environments/{environment_id}/me/permissions{ "team_id": "6f0c...", "principal": "user", "role": "viewer", "custom_role": { "id": "a41b...", "slug": "deployer" }, "scope": null, "actions": ["team:read", "environment:read", "environment:deploy"], "denied": [ { "action": "project:create", "required_role": "developer", "reason": "Action project:create requires developer role or higher; role 'deployer' does not grant it." } ]}actionslists every host action the caller may perform.deniedlists the rest, each with the lowest built-in role that allows it and the same reason a 403 would give. Together they cover every action the platform defines, so an action added later shows up in one of the two lists without a client change.- The answer comes from the same resolution the routes use: the built-in role, the custom role, and unified capability
grants when a team has them switched on. It is advisory. A request is always checked again when it is made, and a
deniedaction can become allowed (or the reverse) if a role changes in between. - A resource-scoped API key has no role:
roleisnull,scopenames its grant, andactionsis the part of that grant that covers the resource asked about. The same key therefore lists its capabilities on its own environment and nothing on the team. - Any team member can read their own permissions, including a viewer. The response never describes anyone else. A
caller who is not a member of the team, or of the environment’s team, gets
404.
Roles are team-wide, so for a signed-in user the environment form returns the same lists as the team form. It exists so a client looking at one environment can ask about exactly that environment, which matters for scoped keys.
Capabilities: can I do this here, now?
Section titled “Capabilities: can I do this here, now?”A permission is only part of the answer. Adding a service also needs the feature to be switched on, and using a GPU
needs a machine that is online with one. The same response carries capabilities, one entry per product-level action:
"capabilities": { "add_service": { "available": true, "reason": null }, "enroll_machine": { "available": false, "reason": "forbidden", "required_action": "grove:manage" }, "use_gpu": { "available": false, "reason": "prerequisite_missing", "prerequisite": { "code": "no_gpu_machine", "message": "None of your machines is online with a GPU.", "fix": "Join a Mac or a Linux machine with an NVIDIA card: run `canopy forest join`." } }}The keys are create_environment, add_service, edit_blueprint, attach_repository, edit_pipeline,
run_pipeline, enroll_machine, manage_machines, use_gpu, configure_previews, configure_protection and
language_settings. reason is null when the capability is available, and otherwise exactly one of:
reason |
Meaning |
|---|---|
forbidden |
The caller lacks a permission; required_action names it. |
feature_off |
The platform feature behind it is switched off for the team. |
prerequisite_missing |
Something real is missing; prerequisite has a code (no_runtime_grove, no_gpu_machine or git_provider_not_connected), a message and a fix. |
Like the rest of the response it is advisory: the route that does the work checks again.
canopy teams permissions <team_id> prints the same answers, and the SDK has teams.mePermissions() and
environments.mePermissions().