Canopy Public API
A predictable, resource-oriented REST API for managing identities, organizational hierarchy, and hierarchical permissions. Every endpoint returns JSON, uses standard HTTP verbs, and is scoped to a single Application and Environment.
https://auth.canopy-io.com/api/v1Authentication
Used for user-delegated actions via OAuth 2.0 flows.
Used for server-to-server communication. Include in the header of your requests.
Your first request
Minimal working example: list identities in your account.
curl -H "X-API-Key: $CANOPY_API_KEY" https://auth.canopy-io.com/api/v1/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.
Issue, list, and revoke the keys that authenticate machine-to-machine access.
Bind roles to identities at any node in the hierarchy, and remove them.
Query the immutable, append-only log of every change across your Application.
Read and change the hosted-page branding an Environment signs people in with.
Stream the incremental change feed to keep an external system in sync.
Read and evolve the node-type schema that defines your org structure.
Create and manage identities and their effective permissions.
Invite identities by email, track pending invites, and revoke outstanding ones.
Build and reshape the organizational tree: create, move, and prune nodes.
Register and manage the OAuth clients behind hosted sign-in, with an API key.
Group identities into customer tenants, each with its own members, invitations, sign-in policy, and directory connection, and let a tenant's own administrators read and grant access at the places beneath it.
Browse the permission catalog and evaluate authorization decisions.
List built-in roles and define custom ones from the permission catalog.
Subscribe to events and receive signed, real-time delivery to your endpoint.
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.