Organizations

Both models run inside the container. A flat Environment holds memberships and roles at the organization node only: a member's roles there apply across the organization. A hierarchy Environment hangs each organization's own tree beneath it, so roles can be scoped to a region or team inside the tenant (see the section on hierarchy below). Switching between the two later works the same way it does without organizations; the organizations and their memberships stay.

Organizations is a Pro plan feature. The gate applies to the management surface only: enabling the container, creating organizations, managing members and invitations, and setting policy. The runtime the feature mints keeps working regardless of billing state. Tokens keep carrying org claims, permission evaluation keeps answering, and your users keep signing in. A billing lapse never breaks your production logins.

The slug is display-only, derived from the name at create and frozen afterwards. Address organizations by id everywhere, and by external_id when all you have is your own account id. If the create succeeded but storing the id on your side failed, the same call again answers 409 and the lookup returns the organization: create-then-store is safe to retry.

The switch is the step teams skip, which ships a session acting in no organization until the next login. A later login can name the organization to start in with the organization field instead. When every person in the Environment should belong to a tenant, turn on Require organization membership under Tenant → Authentication → Sign-in methods: a sign-in, refresh or SSO completion for someone in no organization then answers 403 auth.organization_membership_required until they are added to one, and removing someone's last membership ends their session at its next refresh. The Console shows how many current members that would refuse before you turn it on. The switch assumes the organization exists before a person's first sign-in, which is true of Create an organization on sign-up and of a backend that creates the organization straight after register with its API key. If your app creates the organization in an onboarding step that needs the person signed in, leave it off: their first sign-in would be refused before that step could run. GET /v1/identity/auth/config publishes both switches, so your sign-in and sign-up screens can say what will happen.

For a person who already exists in the Environment, add them directly. role_id is optional: with it the member holds that role from the start, at the organization node or at the office or team node_id names, for the effective_from to effective_to window when you give one; without it they belong and hold nothing until a role is assigned, which is how a person who should act only at one office or team is added. Adding needs no consent from the person: any identity with an active membership in the Environment can be added by id, and the member row answers with their email and name. Adding someone who already belongs answers 409 organization.member_exists: give them the role through the assignment routes instead. That is why only you can do it, with your API key or from the Developer Console: an organization's own administrator, signed in, is refused with 403 organization.member_add_requires_invite and invites by email instead, so the person accepts before joining. A membership added for someone does not move where their next login starts: without an organization named, a login starts in the first organization they joined.

Invite by email when the person should agree to joining, and for anyone with no identity yet. An invitation names where its role is held, the organization node by default or an office or team beneath it with node_id, and optionally the effective_from to effective_to window; with no role_id it admits a member holding nothing, which only the organization node allows. Accepting creates whatever is missing in one step: the identity, its access to the Environment, the membership and the role. Someone who already has an identity in this Environment receives a request to join: accepting is their consent, proven by their existing password or by accepting while signed in, and an organization that requires single sign-on, or a person with a second factor enrolled, accepts only while signed in. Inviting someone who is already a member answers 409 organization.member_exists. Roles are changed, added and removed through the assignment routes (PATCH /api/v1/assignments/:id with the assignment id the member row lists; the organization's own routes under /api/v1/organizations/{org_id}/assignments take the organization node too), and removing a member (DELETE .../members/:identityId) deactivates the membership and every role held at the organization's nodes with it: the identity itself, and its other memberships, are untouched. The member row answers with status, source, joined_at and roles, every assignment held in the organization with its node and effective window; GET .../members?status=deactivated lists the people who left.

With hierarchy on inside the container, a role assignment at a node beneath an organization is a scoped grant on top of the membership, and it requires the membership first: assigning someone at Acme's EU team before they are a member of Acme, or after their membership was deactivated, is refused with 409 organization.membership_required. The same refusal stops a single sign-on arrival placed beneath it and a grant moved there, whenever the membership is not active. An invitation is the exception: accepting one admits the person first, so an invitation may name an office or team directly. A grant at the organization node itself needs no step before it: it admits its holder. Removing the membership removes every role held in the organization with it, and an organization keeps its last administrator: the last active holder of canopy:organization.manage at the organization node can neither be removed nor have that role taken away (409 organization.last_admin).

With @canopy-io/node, read the claims through orgContext(claims) after verifying the token. It returns { orgId, orgRoles, orgRoleIds } or null, and refuses a partial set, or names and ids that do not pair up, rather than letting one claim be read without the others. An empty orgRoles is a member holding no role at the organization node; authorize by evaluating, never by the list.

Switching is a refresh-token operation: Canopy re-verifies the membership, applies the target organization's authentication policy, moves the session, and mints a new access token whose org_id and org_roles name the new organization. Browsers on cookie delivery send the refresh cookie automatically; a backend-for-frontend passes refresh_token in the body alongside its secret API key. Asking to act in an organization the identity does not belong to is refused with a 403. On hosted login the same move is one more authorization request: GET /oauth/authorize?organization=<id> while the browser holds Canopy's hosted session issues a code for that organization with no credential asked again, and refuses a non-member at your callback with access_denied.

When the target organization requires MFA and the session has not yet presented a factor, the switch answers requires_mfa_challenge: true with an mfa_challenge instead of tokens, exactly as login does. The session stays in its current organization until the challenge is verified; the session that verify mints starts in the target. A session that already carries mfa in its amr claim moves without a challenge.

Nothing about the person changed after a switch. Only the context their next requests are decided in did, which is exactly why the same endpoint can answer differently before and after.

Read and write the policy on the organization. The response carries the organization's own values, the Environment baseline it tightens from (environment), and the layered result its members sign in under (effective). The version field backs If-Match. Both routes admit the developer's hierarchy.view / hierarchy.manage and the reserved canopy:organization.manage held at the organization node, the permission you attach to a membership role so a tenant's own admin can set the tenant's policy and nothing else's.

The policy is decided at login for the organization the session starts in, and again at every switch for the organization it moves to, on the Direct API and on the hosted OAuth pages alike. A member with no factor who enters an organization that requires MFA lands in the Environment's grace window (mfa_enrollment_pending), the same way a newly required Environment treats them.

In the Console the binding lives on the organization's Policy tab; the connection's own page lists the organizations it is bound to.

Your own Environment-wide sync is unaffected and stays on the Console's Directory Sync page: it is a directory too, belonging to no organization, and its activity feed and a tenant's never show each other's events.

Both keys are system permissions created in every Environment that has the organizations container on, so there is nothing to register. Add canopy:organization.manage to whichever role means "runs their own organization" in your product, and canopy:access.manage to the one that means "runs their own office", once per Environment. In the Developer Console they sit under Canopy capabilities on the Roles page, above your own permissions and tinted apart from them, because granting it hands authority to people who never sign in to the Console. The same grant over the API looks like this, and note the write replaces the role's whole set, so send its existing keys alongside it.

An organization's members cannot grant themselves this, so the first one comes from you: assign the admin role when you provision the organization, or invite that person with it. After that the organization is self-sufficient: its admins can promote a colleague or hand over entirely, and the last one cannot be removed or demoted.

The organization endpoints accept an identity access token as well as an API key. With a token, every route checks the reserved permission at that organization, so an admin of Acme reads and writes Acme and is refused everywhere else. The one thing they read but cannot write is the list of roles their directory may grant, which stays yours. Only the reserved key opens these routes to a session: Canopy's own management keys, the ones an API key holds as scopes, are never satisfied by a permission you define, so a permission you define under one of those names, such as your own identity.manage, grants nothing: neither these routes, evaluate, the grants the SDK authorizes from, nor the permissions claim count it. Give your own permissions names of their own. One write stays yours: an organization's administrator can reset a member's second factor only while that member belongs to no other organization and signs in to no other Environment of your Account, because a factor is held once per identity and the reset would reach everywhere the person signs in; for a shared member the request answers 409 organization.member_mfa_shared and the reset comes from your own administrators. GET /v1/identity/auth/organizations reports administers (the whole organization) and portal_access (anything inside it) per membership, which is how a session knows what it may open; GET /api/v1/organizations/{org_id}/me then says what, down to the node. Delegate Administration lists the reads an admin screen is built from.

An identity may grant a role only when it holds, at the target node or above, every permission the role carries, the reserved keys included. So an office administrator hands out the roles their office uses and never the one that runs the organization, and nobody promotes themselves: a write outside that line answers 403 assignment.grant_ceiling, on assignments, member role changes and invitations alike. The organization's own administrator, holding canopy:organization.manage at the organization node, is not bounded inside it, so a self-sufficient organization stays one. Console users and your API key are not bounded; the Workspace keeps its own allowlist for its administrators. Delegate Administration shows the escalation it prevents.

Everything above is the same surface the hosted admin portal calls. Build against it when you want these controls inside your own product; send customers to the portal when you would rather not build them at all.

The portal is a client of the same APIs. Every request carries the identity's token and is answered by /api/v1/organizations/:id/* under the tenant admin rule, so what it can do is exactly what the two reserved permissions allow.

With @canopy-io/nestjs, declare the permission with scope: "org". The guard reads org_id off the verified claims CanopyTokenGuard attached and evaluates at that node through the local authorizer, so the check normally costs no network call. A caller acting in no organization is denied without one either.

Without the SDK, ask the evaluate endpoint the same question: node scope, with node_id set to the token's org_id. The two rules that keep tenancy honest: take the organization from the verified token, never from anything the caller sends, and treat a row belonging to a different organization as out of scope before any role is consulted.

Two SDK details for a backend that is not the one verifying the token. resolveOrg, a CanopyModule option, tells the guard where to read the acting organization from when the claims are not on the request under attachTokenAs: a backend-for-frontend that parked them elsewhere, or an API-key surface. Feed it only a value read off a verified token, since it decides which organization's grants answer. orgContext(claims) from @canopy-io/node reads the pair safely, and the amr claim tells you how the session was proven (pwd, otp, or sso, plus mfa once a factor was verified), so a sensitive action can insist on mfa before proceeding.

Worked example. Dana is Admin at Acme and Viewer at Globex; the Viewer role carries read permissions only. The same person, the same endpoints, different answers, decided entirely by which membership the token is exercising:

Evaluation walks a node's lineage with no special case for organizations, and organizations sit directly under the Environment root. So a role assigned at the root is held in every organization: a person with Support at the root can act in Acme and Globex alike, and an org-scoped check answers yes for them in both. That is the place for your own staff. It also means a customer's environment-wide role from before the container was on is a cross-tenant grant until you move that person into memberships: create the memberships first, then remove the root assignment. Removing it touches nothing beneath an organization. A membership, and any scoped grant beneath the organization, reaches only that tenant.

Tokens converge on their own: within the access token's lifetime, every removed or changed membership is reflected in the claims the next refresh mints, and a session acting nowhere lists its remaining memberships with GET /v1/identity/auth/organizations and switches into one.