# Canopy

> Canopy is a hierarchical identity and access-control platform — authentication, organizational hierarchy management, and hierarchical RBAC as a service for B2B applications. This file indexes the documentation and the machine-readable API surfaces for AI agents and other automated readers.

The REST API's base origin is https://auth.canopy-io.com. The OpenAPI documents listed below enumerate every path, parameter, and response schema; an interactive Swagger UI for the same documents is served at https://auth.canopy-io.com/docs.

Every documented API operation also has a human-readable page at https://canopy-io.com/docs/api-reference/{operationId}, where {operationId} is the operation's id from the OpenAPI document (for example ApiPermissionsController_evaluate). Do not guess these URLs from resource names — take the ids from the specs or the sitemap.

Official SDKs: Node.js and TypeScript (`npm install @canopy-io/node`), NestJS (`npm install @canopy-io/nestjs`) — details at https://canopy-io.com/docs/sdks-and-libraries. Every capability also works over plain HTTP via the OpenAPI documents below; do not guess package names beyond these.

Start here: https://canopy-io.com/docs/ai-quickstart — the setup walkthrough written for AI agents, from an empty Environment to a passing permission check.

Canopy has two signed-in applications and the documentation is written for both. The Developer Console is where an integration is built: permissions, roles, hierarchy, keys, OAuth clients, webhooks. Most pages below serve it. The Admin Workspace is where a customer's own staff administer people, and its pages are the Administration set — start at https://canopy-io.com/docs/console-and-workspace for which application a task belongs to, or https://canopy-io.com/docs/what-administrators-can-do for what an administrator can be granted.

## Documentation

- [Canopy Documentation](https://canopy-io.com/docs): Guides, concepts, and the full API reference for Canopy: hierarchical identity and access management for B2B SaaS. Start with the quick start guide.
- [Account Structure | Canopy Docs](https://canopy-io.com/docs/account-structure): How Accounts, Applications, and Environments fit together in Canopy, and which part of your access-control configuration lives at each of those levels.
- [Environments | Canopy Docs](https://canopy-io.com/docs/account-structure/environments): How Environments isolate access-control configuration inside an Application: a separate permission catalog, roles, and hierarchy in each one.
- [AI Quickstart | Canopy Docs](https://canopy-io.com/docs/ai-quickstart): Point an AI coding agent at Canopy's machine-readable surfaces (llms.txt, OpenAPI, sitemap), then drive the API from empty Environment to a passing check.
- [API Keys | Canopy Docs](https://canopy-io.com/docs/api-keys): Authenticate server-to-server requests with scoped, Environment-bound API keys: how to create them, what they reach, and how to rotate them.
- [API Reference | Canopy Docs](https://canopy-io.com/docs/api-reference): Every Canopy endpoint across the public API, identity, OAuth, SCIM, and portal surfaces, with parameters, response shapes, errors, and examples.
- [Assign Roles | Canopy Docs](https://canopy-io.com/docs/assign-roles): Give identities the access a role bundles, one at a time or many at once, scoped to exactly the part of the hierarchy where it should apply.
- [Assign Roles Quickstart | Canopy Docs](https://canopy-io.com/docs/assign-roles/quick-start): Assign roles to identities end to end: a single grant first, then the bulk path for onboarding many people into the same part of your hierarchy.
- [Audit Log | Canopy Docs](https://canopy-io.com/docs/audit-log): An immutable, queryable record of every meaningful change in your Canopy Account: who did what, when, and to which resource it happened.
- [Authentication | Canopy Docs](https://canopy-io.com/docs/authentication): How identities sign in to Canopy. Two paths lead into the same platform, so pick the one that matches how much of the login UI your application owns.
- [Backend Proxy (BFF) Integration | Canopy Docs](https://canopy-io.com/docs/authentication/bff-proxy): Proxy Direct API auth through your own backend so the refresh cookie is first-party, for apps that cannot delegate a subdomain, and for native mobile.
- [Direct API Authentication | Canopy Docs](https://canopy-io.com/docs/authentication/direct-api): Own the login UI and call the identity-auth API directly, including pointing a custom auth domain at Canopy so the refresh cookie stays first-party.
- [Hosted Login | Canopy Docs](https://canopy-io.com/docs/authentication/hosted-login): Let Canopy host the login UI. Your app redirects to /oauth/authorize, the user signs in on Canopy's page, and your callback receives the auth code.
- [Native & Mobile Apps | Canopy Docs](https://canopy-io.com/docs/authentication/native-apps): Sign users in from an installed iOS or Android app: register a native publishable key and store the refresh token in the OS keychain, not a cookie.
- [Authorization Caching | Canopy Docs](https://canopy-io.com/docs/authorization-caching): How a permission check is answered inside your own process, what the SDK caches to do it, and the window before an access change takes effect.
- [Console and Workspace | Canopy Docs](https://canopy-io.com/docs/console-and-workspace): Canopy has two applications you sign in to: the Developer Console and the Admin Workspace. Which one you land in depends on what you administer.
- [Hierarchy | Canopy Docs](https://canopy-io.com/docs/hierarchy): Typed nodes, parent-child rules, and role assignments that cascade down the tree, inside an Environment or beneath each organization.
- [Identities | Canopy Docs](https://canopy-io.com/docs/identities): The end users of your application: Account-level rows holding credentials and federation hints, granted access into specific Applications.
- [Create Identities via API | Canopy Docs](https://canopy-io.com/docs/identities/api-create): Server-to-server identity creation through the public Canopy API, with no email and no acceptance ceremony; the row exists once the call returns.
- [Invite Identities via API | Canopy Docs](https://canopy-io.com/docs/identities/api-invite): Programmatic invitations: your backend issues the invite and Canopy sends the email, or hands the link back so you can deliver it yourself.
- [Create an Identity from the Console | Canopy](https://canopy-io.com/docs/identities/dashboard-create): Admin-driven direct creation: the identity row is written immediately, with an optional starting password and no email confirmation step at all.
- [CSV Identity Import | Canopy Docs](https://canopy-io.com/docs/identities/dashboard-csv-import): A six-step wizard that takes a CSV of identities and either invites them by email, creates Environment-scoped rows, or pre-stages Account records.
- [Invite an Identity from the Console | Canopy](https://canopy-io.com/docs/identities/dashboard-invite): The admin-driven invite flow: Canopy sends the email, and the identity row is created when the recipient follows the link and sets their password.
- [Identities Quickstart | Canopy Docs](https://canopy-io.com/docs/identities/quick-start): Invite your first identity end to end: send the invitation, watch the identity row appear on acceptance, and confirm the access it received.
- [Identity Scope Model | Canopy Docs](https://canopy-io.com/docs/identities/scope-model): How a person exists across three scopes (Account, Application, and Environment), and what invited, joined, and assigned each mean in Canopy.
- [Introduction | Canopy Docs](https://canopy-io.com/docs/introduction): Authorization that matches how organizations actually work, and why flat RBAC breaks as soon as your customers have regions, departments, and teams.
- [Keys & Credentials | Canopy Docs](https://canopy-io.com/docs/keys-and-credentials): Every credential Canopy issues, which integration scenario needs which, and exactly what belongs in your application's configuration for each one.
- [Multi-Factor Authentication | Canopy Docs](https://canopy-io.com/docs/multi-factor): Four factor types (authenticator app, passkeys, email codes, recovery codes) enforced per Environment and tightened per organization.
- [OAuth Clients | Canopy Docs](https://canopy-io.com/docs/oauth-clients): Register an OAuth client so your application can request tokens through Hosted Login or any OIDC-compatible flow, with PKCE required throughout.
- [Organizations | Canopy Docs](https://canopy-io.com/docs/organizations): Multi-tenant access control: an organization per customer, a role per membership, per-organization MFA and SSO policy, and org context in every token.
- [Permissions | Canopy Docs](https://canopy-io.com/docs/permissions): Define the actions your application supports as permission keys, and let Canopy store, enforce, and evaluate access to them for every identity.
- [Permissions Quickstart | Canopy Docs](https://canopy-io.com/docs/permissions/quick-start): Define your permission vocabulary end to end: create the keys your application checks for, then confirm them with a live permission evaluation.
- [Places | Canopy Docs](https://canopy-io.com/docs/places): A place is a region, branch, or team in your organization. Places are how Canopy knows a manager administers one branch and not the one beside it.
- [Quick Start Guide | Canopy Docs](https://canopy-io.com/docs/quick-start): Pick a concept and walk through it end to end. Each guide covers one Canopy feature from first principles to a working example you can run yourself.
- [Roles | Canopy Docs](https://canopy-io.com/docs/roles): Group permissions into roles and assign them to identities, so access is granted by job function rather than one permission key at a time.
- [Roles Quickstart | Canopy Docs](https://canopy-io.com/docs/roles/quick-start): Create your first Canopy role end to end: bundle a set of permissions, name it, and confirm exactly what an identity holding that role can do.
- [SDKs and Libraries | Canopy Docs](https://canopy-io.com/docs/sdks-and-libraries): The official Canopy SDKs for Node.js/TypeScript and NestJS, what they handle that hand-rolled HTTP misses, and how to generate a client for any language.
- [Single Sign-On (SSO) | Canopy Docs](https://canopy-io.com/docs/sso): Let admins and end users authenticate through a corporate identity provider over SAML 2.0 or OIDC, configured per Environment and bound per organization.
- [SSO Quick Start | Canopy Docs](https://canopy-io.com/docs/sso/quick-start): Stand up Single Sign-On end to end: gather the prerequisites, then follow the guide for the surface you are configuring, admin or end user.
- [Webhooks | Canopy Docs](https://canopy-io.com/docs/webhooks): Subscribe to events in your Environment and receive HTTPS callbacks the moment they happen, with signed payloads and automatic retries.
- [Webhook Event Types | Canopy Docs](https://canopy-io.com/docs/webhooks/event-types): Every event you can subscribe a Canopy webhook to, grouped by scope, with the payload each one delivers and the action that fires it.
- [What administrators can do | Canopy Docs](https://canopy-io.com/docs/what-administrators-can-do): Every administrator capability in the Admin Workspace: what each one allows, where it can be granted, and the single capability an owner cannot delegate.
- [Where signing in takes you | Canopy Docs](https://canopy-io.com/docs/where-sign-in-takes-you): One sign-in form, two applications. What you hold decides whether you reach the Developer Console, the Admin Workspace, or a choice between them.
- [Assigning access | Canopy Docs](https://canopy-io.com/docs/workspace-access): How an administrator gives someone a role at a place, which roles they are permitted to hand out, and how moving or removing an assignment works.
- [Account settings | Canopy Docs](https://canopy-io.com/docs/workspace-account-settings): The account's own details in the Admin Workspace, what an administrator can change there, and why almost everything else lives somewhere other than here.
- [Activity | Canopy Docs](https://canopy-io.com/docs/workspace-activity): The activity log in the Admin Workspace: what it records, how it is narrowed to the places you administer, how long it is kept, and how to export it.
- [Administrators and roles | Canopy Docs](https://canopy-io.com/docs/workspace-administrators): Who holds authority in a Canopy account: the administrator roster, what an administrator role is, how one is composed, and how it is granted to a person.
- [Billing | Canopy Docs](https://canopy-io.com/docs/workspace-billing): The subscription behind a Canopy account: what the billing page shows, who may change the plan or the card on file, and the limits a growing account meets.
- [Danger zone | Canopy Docs](https://canopy-io.com/docs/workspace-danger-zone): Deleting a Canopy account: exactly what it removes, what it asks for first, and why it is the one capability an owner cannot delegate to anybody.
- [Environments for administrators | Canopy Docs](https://canopy-io.com/docs/workspace-environments): Why the same organization exists more than once in Canopy, why an administrator's authority stops at one Environment, and what switching between them changes.
- [Administering identities | Canopy Docs](https://canopy-io.com/docs/workspace-identities): The people you administer in the Admin Workspace: who is in your part of the organization, the roles they hold, and what deactivating one actually does.
- [Invitations | Canopy Docs](https://canopy-io.com/docs/workspace-invitations): Invite someone into a place you administer, and what happens next: what they receive, how long it lasts, and what resending or revoking changes.
- [Roles for administrators | Canopy Docs](https://canopy-io.com/docs/workspace-roles): What a role is in Canopy, how a role held by one of your end users differs from an administrator role held by your staff, and who creates each kind.
- [Your responsibility | Canopy Docs](https://canopy-io.com/docs/your-responsibility): The Admin Workspace opens on one screen stating what you administer and what you may do there, including the authority you do not hold. How to read it.

## API specifications

- [Canopy Public API (OpenAPI 3 JSON)](https://canopy-io.com/openapi/api.json): The public machine-to-machine API (/api/v1/*) — identities, permissions, roles, assignments, hierarchy nodes, webhooks, audit events. Authenticate with an API key in the X-API-Key header.
- [Canopy Portal API (OpenAPI 3 JSON)](https://canopy-io.com/openapi/portal.json): The API behind Canopy's signed-in applications (/portal/v1/*) plus identity authentication (/v1/identity/auth/*). JWT bearer authentication.
- [Canopy OAuth 2.0 / OIDC (OpenAPI 3 JSON)](https://canopy-io.com/openapi/oauth.json): OAuth 2.0 / OIDC endpoints (/oauth/*, /.well-known/*) — authorization code with PKCE, token exchange, UserInfo, and discovery. Responses follow the OAuth2/OIDC specifications, not the Canopy envelope.
- [Canopy SCIM 2.0 (OpenAPI 3 JSON)](https://canopy-io.com/openapi/scim.json): SCIM 2.0 directory sync (/scim/v2/*) for IdP connectors — RFC 7643/7644 schemas and envelopes, per-Environment bearer token.
- [Specification index](https://canopy-io.com/openapi): JSON index listing every published OpenAPI document with its URL.

## Machine-readable indexes

- [llms-full.txt](https://canopy-io.com/llms-full.txt): This index plus the full endpoint catalog, authentication and response-envelope reference, and every webhook event type.
- [sitemap.xml](https://canopy-io.com/sitemap.xml): Every page on this site, including one URL per documented API operation.

## Optional

- [Canopy: Hierarchical Identity & Access Management](https://canopy-io.com/): Canopy is hierarchical IAM for B2B SaaS. Model the regions, departments, and teams your customers actually have, with roles that inherit down the tree.
- [Company | Canopy](https://canopy-io.com/company): Canopy is hierarchical identity and access management for B2B SaaS: authentication, enterprise SSO and directory sync, and roles that inherit down the tree.
- [Platform Features | Canopy](https://canopy-io.com/features): Authentication, authorization, and organizational hierarchy as a service: everything you need to stop building access systems and ship your product.
- [Developer Platform & API | Canopy](https://canopy-io.com/features/api-integration): Every action in the dashboard is available programmatically: versioned REST endpoints, JSON, API keys, and webhooks for hierarchical access control.
- [Audit Logging & Compliance | Canopy](https://canopy-io.com/features/audit-logging): Every security-sensitive action is recorded automatically: who did it, what changed, and when. Full context captured, with no instrumentation required.
- [Hierarchical RBAC | Canopy](https://canopy-io.com/features/hierarchical-rbac): Flat roles stop working once your customers have structure. Assign a role at a parent node and it applies to every descendant: one assignment, no migrations.
- [Identity Management | Canopy](https://canopy-io.com/features/identity-management): Manage identities and where they belong. Create users, assign roles at specific hierarchy nodes, and control access from one place: contextual, not global.
- [Multi-Tenant Isolation | Canopy](https://canopy-io.com/features/multi-tenant): Each environment is its own authorization system: its own permissions, roles, and hierarchy, sharing nothing with the next. No cross-environment leakage.
- [OAuth2 & OpenID Connect | Canopy](https://canopy-io.com/features/oauth-authentication): Standards-based OAuth2 and OIDC out of the box: hosted login, mandatory PKCE, and verifiable RS256 JWTs. Your application never handles a password itself.
- [Dynamic Permissions | Canopy](https://canopy-io.com/features/permission-inheritance): Define your own permission vocabulary instead of adopting someone else's roles. Canopy stores, enforces, and evaluates it without hardcoding rules in your app.
- [Scoped Visibility | Canopy](https://canopy-io.com/features/scoped-visibility): Control what users can see, not only what they can do. Canopy scopes the hierarchy server-side, so anything outside a user's assignments never leaves the API.
- [Pricing | Canopy](https://canopy-io.com/pricing): Simple, predictable pricing for hierarchical identity and access management. Start free, upgrade as your team and hierarchy grow, talk to us for enterprise.
- [Privacy Policy | Canopy](https://canopy-io.com/privacy): How Canopy collects, uses, and protects personal data, including the line between data we control and the end-user identity data we process for customers.
- [Security | Canopy](https://canopy-io.com/security): How Canopy protects your identities and authorization logic: credential protection, strong MFA, enterprise SSO, strict tenant isolation, and full auditing.
- [Terms of Service | Canopy](https://canopy-io.com/terms): The agreement between you and Canopy for using the platform, in plain language: who can use the Services, accounts and billing, responsibilities, liability.
- [Use Cases | Canopy](https://canopy-io.com/use-cases): How teams use Canopy's hierarchical access control, from SaaS startups shipping fast to multi-tenant B2B platforms and real enterprise org structures.
- [Enterprise Hierarchy | Canopy](https://canopy-io.com/use-cases/enterprise-hierarchy): Model regions, divisions, departments, and teams exactly as they are structured, and scope permissions to precisely the level where they apply.
- [Multi-Tenant B2B Access Control | Canopy](https://canopy-io.com/use-cases/multi-tenant-b2b): Give every customer a fully isolated environment with its own hierarchy, roles, and permissions: multi-tenancy you don't have to build or maintain.
- [Access Control for SaaS Startups | Canopy](https://canopy-io.com/use-cases/saas-startups): Authentication, role-based access control, and tenant isolation from day one, with a clear path to hierarchy when your customers outgrow flat RBAC.