Where Customers Configure Sign-In

The Three Routes

All three end at the same organization policy and the same connection records. Nothing is a lesser copy of anything else; they differ only in who sits at the keyboard. Which items are available depends on your plan, not on the route: the authentication policy, members and roles are on every plan, and single sign-on, its verified domains and directory sync need Pro or Enterprise, with no limit on how many organizations set them up.

The Developer Console: your own staff

Your team opens an organization and sets it up directly, on Access Control → Organizations → the organization: its authentication policy and single sign-on on the Policy tab, and its directory sync on the Directory sync tab, from choosing the roles a directory may grant to creating its token and mapping its groups. Use it to onboard an enterprise customer whose contract calls for a setting, and to see or repair what a customer has done. It is not for your customers: they have no Console account, and giving them one would hand them your whole Environment.

Our API: inside your own product

You build the settings screen and call the organization endpoints behind it, or skip the screen and have your backend set a customer up when it creates their organization. Your customer never leaves your product and the page is yours to design. You own the work: the screens, the states, the copy, and keeping them current as the policy grows. Either your backend calls with an API key, or the customer's own admin calls with their session token.

The hosted portal: nothing to build

You link your customer's admins to the portal and we render it, wearing your product name, logo, and color. It covers members, who holds a role at each place inside the organization, the authentication policy, single sign-on end to end including the domain and provider setup, directory sync: connecting their identity provider, holding its credential, and mapping its groups to the roles you made available, and, when you let organizations create them, Integrations: credentials for their own systems that act inside the organization with roles from the same list, and Staff Access: whether your support staff may enter the organization, and every time they did or were refused. An office administrator holding canopy:access.manage uses the same portal and sees only its Access page. On Free and Starter the portal leaves out Single Sign-On and Directory Sync, and the single sign-on settings on its Authentication page. An organization that already requires single sign-on keeps that switch so it can be turned off. You build nothing and maintain nothing; what you set is which roles an identity provider may grant, once for the Environment, and each organization's first administrator.

Choosing One

The Console is for your staff and sits alongside whichever of the other two you pick. The real choice is between the API and the portal, and it comes down to one question: is configuring single sign-on part of the experience you want to design, or a chore you would rather hand off?

Pick the portal when you want this working this week, when single sign-on is a checkbox on your enterprise plan rather than a feature you market, or when you would rather not own the identity-provider screens as they change.

Pick the API when the settings page must live inside your product's own navigation, when your design system is part of the sell, or when you already have a settings area these controls belong in.

Pick one, not both. Two customer-facing front doors onto the same policy means two sets of copy to keep true and two places for a customer to be told different things. Nothing stops you switching later: the policy is stored in one place either way.

Whichever you pick, your staff keeps the Console, and the reserved permissions decide who among your customer's people may use the portal or your own page.

Three Rules That Always Apply

Three things hold on all three routes, because they are enforced where the records are stored rather than on any screen.

The Environment is the floor. An organization can tighten what you set for everyone and never loosen it. A write that would go below the floor is refused with organization.policy_loosens, whichever route sent it.

The first admin comes from you. An organization's people cannot grant themselves the right to administer it. You assign a role carrying canopy:organization.manage when you provision the organization; after that its admins manage each other, and the last one cannot be removed.

The roles an identity provider may grant come from you. Which of your roles a customer's identity provider may hand out, through directory sync or a first single sign-on, is your decision. Set it once for the Environment (Authentication → Sign-in methods) and every organization inherits it, or set an organization's own list from its page or with an API key. The organization's admin can read the list and map their groups within it, and is refused with 403 changing it, even at their own organization. The same list bounds the roles an organization may give its own integrations.

Next Step

The reserved permission, the endpoints your own settings page calls, and the portal's own pages are all documented on the Organizations page.

Environment

API version

v1.0

On this page

Was this page helpful?

Tell us how we can improve this guide.