1. Docs
  2. API Reference
REST · JSON · v1

Canopy Public API

v1.0OpenAPI 3.0 All systems operational

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.

Base URLhttps://auth.canopy-io.com/api/v1

Authentication

Bearer TokenOption A
Authorization: Bearer <token>

Used for user-delegated actions via OAuth 2.0 flows.

API KeyOption B
X-API-Key: <your_api_key>

Used for server-to-server communication. Include in the header of your requests.

Your first request

Minimal working example: list identities in your account.

bash — your-terminal
curl -H "X-API-Key: $CANOPY_API_KEY" https://auth.canopy-io.com/api/v1/identities
200 OK application/json 
{
  "items": [
    { "id": "id_01HXABC...", "name": "Production server", "last_used_at": "2026-06-28T14:02:11Z" }
  ],
  "pagination": { "page": 1, "take": 20, "item_count": 3, "page_count": 1 }
}

Response envelope

Every response follows one of a small set of predictable shapes, keyed by the top-level field.

Returns one resource wrapped in data . 
{
  "data": {
    "id": "id_01HXABC...",
    "name": "Acme Realty",
    "createdAt": "2026-04-04T01:23:45.678Z"
  }
}

Errors

Errors use standard HTTP status codes and a consistent envelope. Use the code field for programmatic handling and message as the English fallback for display. 

{
  "error": {
    "statusCode": 404,
    "code": "nodes.node_not_found",
    "message": "Organization node not found",
    "timestamp": "2026-04-04T01:23:45.678Z",
    "path": "/api/v1/nodes/abc",
    "method": "GET"
  }
}
Error code Message
400Validation failed: see details
401Missing or invalid credentials
403Authenticated, but lacks permission
404Resource does not exist
429Rate limit exceeded: see Retry-After header
500Unexpected server error

Conventions

Pagination
Page with page & take (max 100). List responses carry a pagination block.
Timestamps
All datetimes are ISO 8601 in UTC, e.g. 2026-06-28T14:02:11Z.
Idempotency
Send an Idempotency-Key on writes to safely retry without creating duplicates.
Environments
Credentials resolve to a single Environment. They never cross the prod / test line.

Browse endpoints

Endpoints are grouped by resource. Jump into any group to see request parameters, schemas, and live examples.

API Keys 5 endpoints

Issue, list, and revoke the keys that authenticate machine-to-machine access.

GETPOSTPATCHDEL
Assignments 8 endpoints

Bind roles to identities at any node in the hierarchy, and remove them.

GETPOSTPATCHDEL
Audit Events 6 endpoints

Query the immutable, append-only log of every change across your Application.

GETPOSTDEL
Changes 1 endpoints

Stream the incremental change feed to keep an external system in sync.

GET
Hierarchy Schema 2 endpoints

Read and evolve the node-type schema that defines your org structure.

GETPATCH
Identities 21 endpoints

Create and manage identities and their effective permissions.

GETPOSTPATCHDEL
Identity Invites 6 endpoints

Invite identities by email, track pending invites, and revoke outstanding ones.

GETPOSTDEL
Nodes 12 endpoints

Build and reshape the organizational tree: create, move, and prune nodes.

GETPOSTPATCHDEL
Organizations 18 endpoints
GETPOSTPATCHDEL
Permissions 9 endpoints

Browse the permission catalog and evaluate authorization decisions.

GETPOSTPATCHDEL
Roles 7 endpoints

List built-in roles and define custom ones from the permission catalog.

GETPOSTPUTPATCHDEL
Webhooks 7 endpoints

Subscribe to events and receive signed, real-time delivery to your endpoint.

GETPOSTPATCHDEL

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.

Public API spec (/openapi/api.json)Portal & identity auth spec (/openapi/portal.json)OAuth 2.0 / OIDC spec (/openapi/oauth.json)SCIM 2.0 spec (/openapi/scim.json)Specification index (/openapi)AI-agent index (/llms.txt)Full AI-agent reference (/llms-full.txt)
Ready to build?
Jump into any resource group above, or start with the most common first integration.
Browse endpoints
Environment
API version
v1.0
 On this page Was this page helpful?

Tell us how we can improve this guide.

Canopy