Administrators and roles

Overview

An administrator is a member of your staff who administers Canopy. They are not one of the people in your directory: those are your application's end users, and they never sign in here. Everything an administrator can do comes from a role someone granted them, and this is where those roles are made and handed out.

Managing the roster and deciding what the roster may do are two different capabilities. An account can let someone invite and remove administrators without letting them change what any of them can do.

The roster

Two lists sit behind the Administrators section, and they answer different questions.

The people list is everyone who is a member of the account, whether or not they hold any authority. Being on it means they can sign in to Canopy; it does not mean they can do anything.

The assignments list is one row per grant: who holds which role, and how far it reaches. This is the list to read when the question is what someone can actually do.

Inviting an administrator always names a role, because there is no such thing as an administrator who holds nothing. Accepting the invitation grants that role immediately, so choose it before you send.

A pending invitation's role can be changed without invalidating the link already emailed. An unaccepted one lasts seven days and can be resent, which issues a new link.

Deactivating, removing, revoking

Three different actions, often confused. Deactivating blocks someone's access to this account while keeping their record and their grants, and is reversible. Removing deletes their membership: they lose access, and coming back means a fresh invitation. Revoking a grant leaves them an administrator and takes away one particular role. None of the three touches the people in your end-user directory.

Two people are out of reach: you cannot deactivate or remove yourself, and nobody can deactivate or remove the account owner. Retiring an owner means transferring or deleting the account.

What a role is

A role is a named bundle of capabilities, and nothing else. It carries no place of its own: capabilities apply wherever the grant applies, so the same role means one place for one person and a whole Environment for another. That is why granting is a separate step from composing, and why a role can be reused rather than rebuilt per person.

Composing one

Creating a role takes two decisions, and one of them is permanent.

Where it applies: account-wide, carrying authority over the account with no Environment; or in one Environment, optionally narrowed to a place when it is granted. This cannot be changed afterwards, because every grant of the role depends on it.

Which capabilities it carries, chosen from the platform's fixed catalog. You compose from that list rather than inventing entries, because a capability only means something if Canopy enforces it. The choice is bounded by the scope you picked: an account-wide role cannot carry an Environment capability, or it would have nowhere to apply.

Some roles are built in. Their names and capabilities are platform constants, so they can be neither edited nor deleted; create a custom role when you need something different.

A custom role can be deleted only once nobody holds it. While anyone still does, deletion is refused and tells you how many grants stand in the way.

Granting one

Granting attaches a role to a person, and the role decides the shape. An account-wide role names no Environment and applies everywhere. An Environment role names one Environment, and can be narrowed to a single place and everything beneath it, which is what makes a regional administrator regional. Revoking a grant takes effect at once and cannot be undone: granting again means making a new one.

A grant can also carry a window: a date the authority begins, a date it ends, or both. Left blank, it begins at once and does not expire. The same role can be held for separate periods, one grant per period; what is refused is a second grant identical to one already live for an overlapping period, because two copies of the same authority add nothing, and revoking one of them would look like removal while the other kept it alive. Windows are set through the API today rather than on any screen.

A role can also carry a ceiling on what its holder may hand out to end users, which is why the roles offered on the assignment screen are narrower than the roles that exist. That ceiling is configured through the API today rather than on any screen, so setting it is a request to whoever builds your integration.

The owner

The account owner holds every capability implicitly, without being granted anything, and can delegate all of them. Composing roles and granting them is itself a capability rather than a special status, so an owner can hand that out too. Exactly one thing cannot be delegated by any means: deleting the account.

Next Step

One account-wide authority has its own page, because the questions it raises are different: Billing covers the subscription and who may change it.

Environment

API version

v1.0

On this page

Was this page helpful?

Tell us how we can improve this guide.