Authentication model

A Tenant owns Users and one or more Environments. Almost every call to Poly is authorized with an API key bound to one Environment. Canopy’s default login pastes that key. Enterprise SSO still mints a short-lived API key after OIDC.

Use this page to tell Users, keys, Canopy, and SSO apart. How-tos: Managing Users and API Keys, Setting up Single Sign-On.

Which path

Situation

Path

You just signed up

Day-1 admin key → /canopy/polyui/login and CLI setup

Adding a teammate who will use the CLI / PolyUI

Create User, mint an environment key, they paste their key

Enterprise browser login

OIDC IdP + PUBLIC Application + permission policies (Setting up Single Sign-On)

The pieces

Piece

Role

Tenant

Company / billing boundary on an instance (na1, eu1, …)

Environment

Isolation unit for resources and keys

User

Tenant-scoped person. Creating a User does not grant access by itself

API key

Secret bound to one Environment and to either a User or an Application. Shown in plaintext once

Application

Canopy / custom app config. SSO login apps must be visibility=PUBLIC (Setting up Single Sign-On)

Identity Provider

OIDC registration for the tenant. SAML is not supported for customers yet

Permission Policy

Grants a permission set and which environments an SSO user may enter

Day-1 signup

Sign up on the instance, verify email, copy the admin API key. You cannot retrieve that plaintext later. Create a new key if you lose it.

That first key is full-admin on the tenant’s default environment. Paste it into /canopy/polyui/login and into npx poly setup / python -m polyapi setup.

Add a teammate (API key portal)

  1. Create a User (tenant-level).

  2. Mint an Environment-scoped API key for that user with the permissions they need.

  3. They log into Canopy with their key, not yours.

Users exist at the tenant. Keys exist at the environment. A user can have different keys in dev and prod.

Canopy login modes

Path

URL

What happens

Default Poly UI

/canopy/polyui/login

Paste an API key. The browser uses it as Bearer for portal APIs

SSO Application

/canopy/<subpath>/login

OIDC button(s). Poly mints an SSO API key (expiry from the token). Typical template sets allowPolyApiKey: false so that app does not offer key paste

SSO still requires:

  • User records with SSO sub (or a mapping that may create the User)

  • Permission policies that include at least one environment

  • Application visibility=PUBLIC

A User with zero keys and no policy that mints/binds access cannot use resources via SSO. See Setting up Single Sign-On and Permission Policies.

If SSO looks broken only for other people, the Application is often still TENANT. See the warning on Setting up Single Sign-On.

Roles vs permissions

User role (Admin vs User) is not a substitute for key permissions. Admin role does not by itself grant manage-users or tenant admin on a key. SuperAdmin is a platform role, not a tenant setting.

MFA is optional hardening. See Enable MFA for Your Tenant.