SDKs and Libraries | Canopy Docs

Official SDKs

Maintained by the Canopy team. They wrap the response envelope, pagination and retries so you do not hand-roll HTTP calls, and they answer token verification and permission checks inside your own process, so neither costs a call to Canopy on every request.

Node.js and TypeScript

Requires Node 18 or later, and runs unchanged anywhere fetch exists: browsers, Cloudflare Workers, Deno. Ships ESM and CommonJS with generated types and zero runtime dependencies.

npm install @canopy-io/node

NestJS

A module that registers the client as an injectable provider and a guard that evaluates a permission on a route, so authorization is a decorator rather than a call in every handler. Three scopes: node, app_wide, and org, which decides inside the organization the caller's token is acting in. Requires NestJS 10 or 11.

npm install @canopy-io/nestjs

For AI coding assistants

The Canopy agent skill teaches an AI coding assistant to integrate with these SDKs the way these docs describe: choosing the sign-in shape, verifying tokens with the right audience, authorizing in-process, and failing closed. It lives in the SDK repository and is released with the packages.

Install it in Claude Code

Other assistants read the same Markdown files directly: point them at SKILL.md, or at the repository's AGENTS.md, which links to it.

/plugin marketplace add canopy-identity/canopy-javascript /plugin install canopy@canopy-javascript

What the SDKs handle for you

Writing a fetch call against a documented REST API is straightforward. These are the parts that are easy to get subtly wrong, and they are why the hand-written layer exists.

Verifying an access token. Canopy signs tokens RS256 and publishes the keys, so the SDK checks them in-process: one key fetch, then no network. The traps are why it ships rather than being left to each caller: pinning the algorithm so alg:none and HMAC key-confusion cannot get in, bounding refetches so a forged key id cannot hammer the issuer, refusing to ignore an audience the token carries (a Hosted Login token names your client_id, so pass audience; a Direct API token carries none, so leave it unset), and refusing a pre-auth token: genuine and correctly signed, but issued before the user picked an Account. It accepts identity tokens only, unless you name other token types in allowedTypes. A machine client's service token is admitted per call instead, with verify(token, { alsoAllow: ["service"] }) or @AllowServiceTokens() on a NestJS route, and held to serviceAudience, the audience your API answers to; there the local authorizer reads the client's own grants. orgContext(claims) reads the organization a token acts in as { orgId, orgRoles, orgRoleIds }, the names and ids of the roles held at that organization's node, possibly empty; it is null for a session outside any organization. While Canopy is unreachable it keeps verifying with the keys it already holds, and a token signed by a key it has never seen answers 503 (token.jwks_unavailable) rather than 401.

Answering permission checks without a call per request. Rather than asking “may this identity act here” every time, the SDK asks “where may it act” once and walks your hierarchy in memory. A grant already means a node and everything beneath it, so what is cached stays small even for an administrator granted near the root, and the hierarchy is revalidated on the same short window as the grants, because moving a node changes what an inherited grant reaches even though no grant changed.

Retry safety. GET, HEAD, PUT and DELETE are idempotent by HTTP definition and are retried on a 5xx. POST is not, so a blind retry there could create a second role assignment. A 429 is always retried, because the request was refused before anything happened.

Two pagination styles behind one shape. The audit log and the change feed are cursor-paginated and everything else is offset, but the top-level response looks identical either way, so a hand-rolled loop can silently read only the first page, or never terminate.

The response envelope. Single items arrive under data, collections under items, paginated collections with a pagination block, partial success as a summary plus per-item results, failures under error, and deletes as a bare 204.

Typed error codes. Branching on a stable code such as rbac.assignment_conflict survives a message being reworded.

No SDK for your language?

Every Canopy capability is available over plain HTTP. The API is described by an OpenAPI specification published at a stable URL, so you can generate a typed client for any language your toolchain supports, or call the endpoints directly.

OpenAPI specification

Feed this document to a generator and get a typed client in the language you build in. It is the same specification that renders Canopy's own API reference, so it never drifts from the live API.

/openapi/api.json

Check a permission with curl

Or skip the generator. Every endpoint is a plain HTTP call.

curl -X POST https://auth.canopy-io.com/api/v1/permissions/evaluate \
  -H "X-API-Key: $CANOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "identity_id": "7d3f9b2e-4c1a-4e8b-9f2d-1a6c5e0b8f34",
        "permission": "orders.refund",
        "scope": "node",
        "node_id": "e6b2d8f4-9a1c-4d7e-8b3f-2c5a9e1d6f48"
      }'

Always send a scope

scope is required. Use node to ask whether the identity holds the permission at node_id, walking the lineage so a grant on an ancestor is inherited. Use app_wide for the coarse “anywhere in this Environment” question: useful for hiding a menu item, never for guarding a resource that belongs to a node.

Filter a list by access with curl

The answer names the grant roots and, up to max_nodes, every node beneath them, or env_wide when every node qualifies. Filter your own table by it. The SDK computes the same answer from its cache; this is the fresh one, for a process that does not run the SDK.

curl "https://auth.canopy-io.com/api/v1/identities/7d3f9b2e-4c1a-4e8b-9f2d-1a6c5e0b8f34/accessible-nodes?permission=orders.view" \
  -H "X-API-Key: $CANOPY_API_KEY"

Versioning

The SDK follows semantic versioning. While it is on a 0.x release the surface may still change between minor versions, so pin the minor if you need that stability. The generated types are checked against the published specification on every pull request, before every release, and weekly in between, so drift is reported rather than found by a consumer. A run that cannot reach the specification skips the check with a warning rather than failing. The local authorizer is held to the API the same way: its suite replays the authorization conformance cases Canopy publishes at /conformance/authorization.json, the cases the API's own suite replays. The grant and parent-edge responses it evaluates from carry a model_version, and an SDK that does not know the version it is served refuses with CanopyAuthorizerError rather than guessing, so an older SDK never allows what the API has started to deny.

Environment

API version

v1.0

On this page

Was this page helpful?

Tell us how we can improve this guide.