SAML SSO and SCIM
Canopy Host supports team-scoped SAML single sign-on (SSO) and SCIM 2.0
user provisioning. The host.sso capability is generally available and
enabled by default. Configuration and token management require the team
owner; API requests are also subject to the account’s authorization.
Configure SAML
Section titled “Configure SAML”Create the SSO connection with the identity provider’s entity ID, SSO URL, and signing certificate. Set allowed email domains before enabling the connection. Configuration and activation are separate so you can test the settings first.
canopy sso status --team <team-id>canopy sso test --team <team-id>The test command checks whether the connection has the required settings. Configure or update the connection through the Host API:
PUT /teams/{team_id}/ssoContent-Type: application/json
{ "provider": "okta", "idp_entity_id": "https://idp.example.com/entity", "idp_sso_url": "https://idp.example.com/sso", "idp_certificate": "-----BEGIN CERTIFICATE-----...", "allowed_email_domains": ["example.com"]}The API response supplies the service-provider metadata and assertion
consumer URLs. Do not include the signing certificate in logs or commit
it to source control. Only admin, developer, or viewer can be
assigned by SSO; the owner role remains tied to the team’s owner.
Group-to-role mappings use the same assignable roles.
Enable SSO after verifying the identity-provider configuration:
PUT /teams/{team_id}/sso/enabledContent-Type: application/json
{"enabled": true}Use {"enabled": false} to turn it off. Removing the SSO connection does
not remove existing team members. See the Host API reference
for complete request and response contracts.
Provision users with SCIM
Section titled “Provision users with SCIM”Create a dedicated SCIM token and configure it as a bearer credential in your identity provider. The plaintext is returned only when created; save it in your secret manager. Rotating the token invalidates the previous one immediately.
canopy scim token rotate --team <team-id>canopy scim token revoke --team <team-id>SCIM requests use Authorization: Bearer <scim-token> and the SCIM 2.0
resource paths /scim/v2/Users and /scim/v2/Groups. This credential is
separate from a Canopy user token and an API key. The current Users
surface supports listing, reading, creating, patching and disabling
users; Groups supports listing, reading and patching groups. Deleting a
user disables sign-in rather than hard-deleting the Canopy account.
Only the Users userName eq "value" filter is recognized; unsupported
filter expressions do not become broader server-side queries. See the
Host API reference for SCIM response formats and supported operations.
Access and availability
Section titled “Access and availability”The team owner manages the SSO connection and SCIM token. The server
checks sso:manage and scim:manage permissions as well as the
host.sso feature. A CLI command or MCP tool being available does not
grant permission. Check with your Canopy administrator if the feature is
unavailable for your team.