Canopy Portal API
The API behind Canopy's two signed-in applications. Authenticated with a user JWT and scoped to an Account and Application by path, it manages the same resources your team works with in the UI.
https://auth.canopy-io.com/portal/v1/accounts/{accountSlug}/applications/{appSlug}Authentication
Used for user-delegated actions via OAuth 2.0 flows.
Your first request
Minimal working example: list identities in your account.
curl -H "Authorization: Bearer $CANOPY_TOKEN" \ https://auth.canopy-io.com/portal/v1/accounts/acme/applications/prod/environments/production/identities
{ "items": [ { "id": "8f14e45f-ceea-467a-9b36-2c0b6f1c3e21", "email": "alex@acme.com", "first_name": "Alex", "last_name": "Rivera", "is_active": true, "created_at": "2026-06-28T14:02:11Z" } ], "pagination": { "page": 1, "take": 20, "item_count": 1, "page_count": 1, "has_previous_page": false, "has_next_page": false } }
Response envelope
Every response follows one of a small set of predictable shapes, keyed by the top-level field.
data . { "data": { "id": "2c6a9b1e-7f3d-4a58-8e21-5b9c0d4f6a13", "name": "Acme Realty", "created_at": "2026-04-04T01:23:45.678Z" } }
Errors
code field for programmatic handling and message as the English fallback for display.
{ "error": { "statusCode": 404, "code": "hierarchy.node_not_found", "message": "Node not found", "timestamp": "2026-04-04T01:23:45.678Z", "path": "/api/v1/nodes/3f2a1b9c-7d4e-4c8a-b6f5-0e9d8c7b6a51", "method": "GET" } }
| Error code | Message |
|---|---|
| 400 | Validation failed: see details |
| 401 | Missing or invalid credentials |
| 403 | Authenticated, but lacks permission |
| 404 | Resource does not exist |
| 429 | Rate limit exceeded: see Retry-After header |
| 500 | Unexpected server error |
Conventions
Browse endpoints
Endpoints are grouped by resource. Jump into any group to see request parameters, schemas, and live examples.
Register, sign in, and manage sessions for platform admins.
Enroll and manage an administrator's own multi-factor authenticators.
Satisfy an administrator's in-flight MFA challenge with a code, passkey, or recovery code.
Register and manage the OAuth clients behind hosted sign-in.
List and create the Applications under an Account.
Manage identities across the whole Account, including bulk operations.
Invite identities at the Account tier and track their status.
Review and force-reset an identity's MFA enrollment as an admin.
List and remove the platform admins who can manage the Account.
Subscribe to Account-level events and manage signed delivery.
Read, rename, and delete the Account that owns your Applications.
Grant and revoke administrator roles across the Account.
Define what an administrator can be, and how far it reaches.
Issue, scope, list, and revoke Application API keys.
Read, rename, and delete an individual Application.
Query, live-tail, and export the admin audit log.
Query, live-tail, and export the end-user identity audit log.
Serve hosted sign-in from your own subdomain, and verify its DNS.
Create and configure the Environments within an Application.
Build and reshape the organizational tree: create, move, and prune nodes.
Create and manage identities and their role assignments in an Application.
Invite identities to an Application and manage pending invites.
What the signed-in user may do, and which products they open.
Save, update, and delete your personal audit-log views.
Read and update your Developer Console preferences.
Create an Environment's organizations and manage their members, policy, SSO bindings, and the roles each one's directory may grant.
Create, rename, and revoke the web and native keys that front-end sign-in uses.
Assign roles to identities at any node, and review coverage.
Browse the permission catalog and explain authorization decisions.
List built-in roles and define custom ones from the permission catalog.
Map IdP-pushed SCIM groups to roles at a node.
Mint and manage the SCIM bearer tokens that drive directory sync.
Bootstrap an Environment's permission catalog and starter roles.
Check setup status across every Environment in the Account.
Read an Environment's token-signing keys and rotate them on demand.
Configure inbound SSO connections for end-user login.
Invite platform admins to the Account and track their status.
List and inspect the platform admins in the Account.
Subscribe to Application events and manage signed delivery.
The operator surface, scoped to the caller’s own grants.
The Environments the caller may operate in.
Machine-readable API
Everything in this reference is generated from OpenAPI 3 documents you can fetch directly. Point a code generator, your own tooling, or an AI agent at the same source the docs are built from.
Tell us how we can improve this guide.