Skip to main content
Access control decides what each member of a team can do and where. Every API key acts as the member who created it, so the same rules decide what a key can do. These endpoints let you manage those rules without the console.

​
How access is decided

1

Role

Every member has one role. The built-in roles are tenant_owner, tenant_admin and tenant_member; you can add custom roles. A role holds a set of actions, such as project:modify or member:invite. List Roles shows the roles of your team, and the permission catalog lists every action you can grant.
2

Permission rules

A permission rule allows one more action, either for a custom role or for a single member. The built-in roles cannot be changed.
3

Access groups

An access group bundles permissions, and optionally a list of resources, and gives them to every member you add to it.
4

Access scope

An access scope narrows a role to listed resources of a type — for example, only two of the team’s workspaces. A scope only limits: it never grants more than the role allows. A resource type with no scope is unrestricted.
5

Resource access

On a single resource, you can give a member a permission level (read, write or manage), or add the resource to someone’s restricted scope. See Resource access below.
To see the result for one member or access group, with the source of each permission, use Get Member Effective Permissions or Get Access Group Effective Permissions. To check what your own key can do, use List My Permissions.

​
Resource access

The resource access endpoints work the same way for every resource type that can be shared one resource at a time. The path names the type and the resource:

​
Conditional writes

Writes that replace a whole list — access scopes and an access group’s permissions — return an ETag header. Send it back in If-Match on the next write: if someone changed the list in the meantime, the write is refused with 412 and nothing changes.

​
Protecting admins

Some changes affect what an admin can do: giving someone an admin role, or narrowing an admin’s access. Only the team owner or an admin can make them. When anyone else tries, the request is refused with 403, and data.operation in the error names the change — see Errors.