@canopy-io/node 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -22,6 +22,20 @@ interface CursorPagination {
 type Pagination = OffsetPagination | CursorPagination;
 declare function isCursorPagination(pagination: Pagination): pagination is CursorPagination;
 /** A collection response, paginated or not. */
+/**
+ * The answer to a conditional read.
+ *
+ * A discriminated union rather than an optional body, so a caller cannot
+ * mistake "nothing changed" for "changed to nothing" — the two are opposite
+ * instructions to whatever is holding the cached copy.
+ */
+type ConditionalResult<T> = {
+    modified: true;
+    data: T;
+    etag: string | null;
+} | {
+    modified: false;
+};
 interface Collection<T> {
     items: T[];
     pagination?: Pagination;
@@ -59,6 +73,14 @@ interface CanopyClientOptions {
     timeoutMs?: number;
     /** Retries after the first attempt. Defaults to 2. */
     maxRetries?: number;
+    /**
+     * Ceiling on a single wait between attempts. Defaults to 30s.
+     *
+     * The server's `Retry-After` is honoured up to this, then clamped. Without a
+     * cap the wait is whatever a response header asks for, which sits outside
+     * `timeoutMs` and can hold a caller far longer than its own budget allows.
+     */
+    maxBackoffMs?: number;
     /** Extra headers on every request. */
     headers?: Record<string, string>;
     /** Injectable for tests and for runtimes with a non-global fetch. */
@@ -68,17 +90,67 @@ interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     body?: unknown;
     signal?: AbortSignal;
+    /**
+     * Per-attempt deadline for this call only, overriding the client-wide
+     * `timeoutMs`. 0 disables it.
+     *
+     * The client-wide default suits administrative CRUD. A latency-critical call
+     * on a request path — an authorization check on every inbound request — wants
+     * a much tighter one, because the total time at risk is this deadline times
+     * the attempts, and it is spent holding an inbound request open.
+     */
+    timeoutMs?: number;
+    /**
+     * Retries after the first attempt for this call only, overriding the
+     * client-wide `maxRetries`. 0 disables retrying.
+     *
+     * Set this together with `timeoutMs` when a call needs a bounded worst case:
+     * the two multiply. A deadline alone still permits `maxRetries + 1` of them
+     * back to back, which is the difference between a slow call and a request
+     * held open long past the point the answer was useful.
+     */
+    maxRetries?: number;
+    /**
+     * Ceiling on a single wait between attempts, for this call only.
+     *
+     * Set it alongside `timeoutMs` and `maxRetries` when a call needs a real
+     * worst case: the deadline bounds an attempt, `maxRetries` bounds how many,
+     * and this bounds the waiting in between — which a server's `Retry-After`
+     * would otherwise control.
+     */
+    maxBackoffMs?: number;
+    /**
+     * Headers for this call only, overriding the client-wide `headers`.
+     *
+     * This is how the per-request protocol headers are sent: `If-Match`, carrying
+     * a resource's current `version` for optimistic concurrency (a stale value
+     * answers 409), and `Idempotency-Key`, which makes a replayed bulk create
+     * return the original result instead of creating rows twice.
+     *
+     * The credential is not overridable this way — auth is settled by the client.
+     */
+    headers?: Record<string, string>;
     /**
      * Declares this call safe to repeat, which allows retrying a 5xx.
      *
-     * Needed because the OpenAPI document only marks one operation
-     * `x-canopy-idempotent`, so the spec cannot drive this. GET, HEAD, PUT and
-     * DELETE are treated as idempotent by HTTP definition; POST is not, and a
-     * blind retry there can create a second role assignment or a second
-     * invitation. Set this only when the endpoint genuinely tolerates a repeat.
+     * Needed because the generated types carry no idempotency marker, so the
+     * spec cannot drive this. GET, HEAD, PUT and DELETE are treated as
+     * idempotent by HTTP definition; POST is not, and a blind retry there can
+     * create a second role assignment or a second invitation.
+     *
+     * Set it where a POST is a read in disguise — the permission evaluations
+     * take a body and so must be POSTs, but they compute an answer and write
+     * nothing. Do not set it on anything that creates.
      */
     idempotent?: boolean;
 }
+/**
+ * The per-call knobs a resource method accepts.
+ *
+ * Deliberately excludes `body` and `query`, which the method itself owns, and
+ * `idempotent`, which is a property of the endpoint rather than the call site.
+ */
+type CallOptions = Pick<RequestOptions, "signal" | "timeoutMs" | "maxRetries" | "maxBackoffMs" | "headers">;
 /**
  * The transport every resource is built on: one place that knows how to
  * authenticate, unwrap Canopy's response envelope, turn a failure into a typed
@@ -91,6 +163,7 @@ declare class CanopyClient {
     private readonly baseUrl;
     private readonly timeoutMs;
     private readonly maxRetries;
+    private readonly maxBackoffMs;
     private readonly authHeaders;
     private readonly extraHeaders;
     private readonly fetchImpl;
@@ -107,6 +180,29 @@ declare class CanopyClient {
      * `CanopyConnectionError`.
      */
     request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * A conditional read: send the validator you already hold, and find out
+     * whether anything changed.
+     *
+     * The sibling of `If-Match`, which this client already sends for optimistic
+     * concurrency. `304 Not Modified` is a *success* — it means the copy you
+     * have is current — but it is not a 2xx, so `request` would raise it as an
+     * error. Hence a separate entry point with a return type that says which
+     * happened rather than one that has to be inspected.
+     *
+     * Use it to hold something expensive and revalidate cheaply — the hierarchy
+     * behind local authorization is the case this exists for.
+     */
+    requestConditional<T>(method: string, path: string, etag: string | undefined, options?: RequestOptions): Promise<ConditionalResult<T>>;
+    /**
+     * Everything up to the response: retries, backoff, cancellation and the
+     * status check, without deciding what the body means.
+     *
+     * Split out so a conditional read can accept `304` where an ordinary one
+     * must not, rather than either duplicating the retry policy or teaching
+     * `unwrap` about statuses that carry no body.
+     */
+    private perform;
     private shouldRetry;
     private send;
     private buildUrl;
@@ -231,6 +327,26 @@ interface paths {
         patch: operations["ApiPermissionsController_updatePermission"];
         trace?: never;
     };
+    "/api/v1/permissions/{id}/usage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get where a permission is used
+         * @description Returns the roles that grant a permission, each with the number of distinct identities holding that role, plus `role_count` and the distinct `identity_count` the permission reaches overall. Because a permission is only ever held through a role, this is the full blast radius of deleting it — the listed roles are exactly the ones a delete would strip it from. Deactivated roles are included; `identity_count` is not the sum of the per-role counts, since one identity may hold several granting roles. Returns `404` when no permission with that id exists in the Environment. Requires the `rbac.view_roles` permission.
+         */
+        get: operations["ApiPermissionsController_getPermissionUsage"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/permissions/evaluate": {
         parameters: {
             query?: never;
@@ -643,6 +759,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/identities/{id}/grants": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get where an identity holds each permission
+         * @description Returns, for the current Environment, every permission the identity holds mapped to the hierarchy nodes its grants were made at — the nodes themselves, **not** expanded through their descendants. A grant already means "this node and everything beneath it", so a caller answers a node-scoped question by walking up from the node in question and looking for one of these roots, using a copy of the tree fetched once from `GET /api/v1/nodes` and shared across identities. Answers both scopes without a further call: the permission appearing at all is the Application-wide answer, and the walk is the node-scoped one. Scheduled assignments outside their effective window are excluded. Returns `404` when the identity has no membership in this Environment.
+         */
+        get: operations["ApiIdentitiesController_getIdentityGrants"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/identity-invites": {
         parameters: {
             query?: never;
@@ -771,6 +907,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/nodes/parents": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List the hierarchy as parent edges
+         * @description Returns the same hierarchy `GET /api/v1/nodes` describes, scoped identically, but as a flat list of `{ id, parent_node_id }` and nothing else. Intended for a client that evaluates authorization locally: it walks upward from a node and reads none of the tree's names, statuses, access flags or counts. At fifty thousand nodes the tree is roughly 18.6 MB against 4 MB of edges, on a read that runs at every consuming process's startup. Supports the same `If-None-Match` revalidation, with a validator distinct from the tree's — a tag from one representation never satisfies a request for the other.
+         */
+        get: operations["ApiNodesController_listNodeParents"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/nodes/{id}": {
         parameters: {
             query?: never;
@@ -1462,6 +1618,24 @@ interface components {
             /** @description One or more permissions to register */
             permissions: components["schemas"]["PermissionItemDto"][];
         };
+        PermissionUsageRoleDto: {
+            id: string;
+            name: string;
+            description?: string | null;
+            is_system_role: boolean;
+            /** @description Deactivated roles still carry the grant, so they are listed too — deleting the permission strips it from them as well. */
+            is_active: boolean;
+            /** @description Number of distinct identities assigned this role, across all nodes. */
+            member_count: number;
+        };
+        PermissionUsageDto: {
+            permission_id: string;
+            /** @description Number of roles that grant this permission. */
+            role_count: number;
+            /** @description Distinct identities that hold this permission through any granting role. Lower than the sum of `member_count` when an identity holds more than one granting role. */
+            identity_count: number;
+            roles: components["schemas"]["PermissionUsageRoleDto"][];
+        };
         UpdatePermissionDto: {
             /** @description Updated name */
             name?: string;
@@ -1470,18 +1644,6 @@ interface components {
             /** @description Updated category */
             category?: string;
         };
-        EvaluatePermissionDto: {
-            /** @description Identity ID (from the `identities` table — the end user being evaluated, not an admin). */
-            identity_id: string;
-            permission: string;
-            /**
-             * @description Required. `node` asks 'does this identity have the permission *at* `node_id`?' (lineage walk). `app_wide` asks the coarse-grained 'does this identity have the permission *anywhere* in the org?' question — useful for UI gating, **never** for resource-scoped enforcement. `node` requires `node_id`; `app_wide` forbids it.
-             * @enum {string}
-             */
-            scope: "node" | "app_wide";
-            /** @description Required when `scope` is `node`; must be omitted when `scope` is `app_wide`. */
-            node_id?: string;
-        };
         EvaluateResponseDto: {
             allowed: boolean;
             permission: string;
@@ -1495,6 +1657,18 @@ interface components {
             granting_roles: string[];
             denial_reason?: string | null;
         };
+        EvaluatePermissionDto: {
+            /** @description Identity ID (from the `identities` table — the end user being evaluated, not an admin). */
+            identity_id: string;
+            permission: string;
+            /**
+             * @description Required. `node` asks 'does this identity have the permission *at* `node_id`?' (lineage walk). `app_wide` asks the coarse-grained 'does this identity have the permission *anywhere* in the org?' question — useful for UI gating, **never** for resource-scoped enforcement. `node` requires `node_id`; `app_wide` forbids it.
+             * @enum {string}
+             */
+            scope: "node" | "app_wide";
+            /** @description Required when `scope` is `node`; must be omitted when `scope` is `app_wide`. */
+            node_id?: string;
+        };
         EvaluateCheckDto: {
             /** @description Identity ID (from the `identities` table — the end user being evaluated, not an admin). */
             identity_id: string;
@@ -1510,13 +1684,6 @@ interface components {
         BulkEvaluatePermissionDto: {
             checks: components["schemas"]["EvaluateCheckDto"][];
         };
-        ExplainPermissionDto: {
-            /** @description Identity ID (from the `identities` table — the end user being explained, not an admin). */
-            identity_id: string;
-            permission: string;
-            /** @description The hierarchy node to explain the decision at. The lineage from the root to this node is walked and returned in the trace. */
-            node_id: string;
-        };
         PermissionTraceAssignmentDto: {
             assignment_id: string;
             role_id: string;
@@ -1552,6 +1719,13 @@ interface components {
             /** @description Root-first lineage of the target node, each with the identity's assignments observed at that node. */
             lineage: components["schemas"]["PermissionTraceNodeDto"][];
         };
+        ExplainPermissionDto: {
+            /** @description Identity ID (from the `identities` table — the end user being explained, not an admin). */
+            identity_id: string;
+            permission: string;
+            /** @description The hierarchy node to explain the decision at. The lineage from the root to this node is walked and returned in the trace. */
+            node_id: string;
+        };
         PageMetaDto: {
             /** @description Current page number (1-based) */
             page: number;
@@ -1584,6 +1758,10 @@ interface components {
             name: string;
             node_id: string;
             node_name: string;
+            /** @description When this assignment starts; null means it is already active */
+            effective_from: string | null;
+            /** @description When this assignment expires; null means it never does */
+            effective_to: string | null;
         };
         IdentityRowDto: {
             id: string;
@@ -1714,6 +1892,12 @@ interface components {
             /** Format: date-time */
             updated_at: string;
         };
+        IdentityGrantResponseDto: {
+            /** @example reports.view */
+            permission: string;
+            /** @description Hierarchy node ids the permission was granted at. Not expanded through descendants. */
+            nodes: string[];
+        };
         IdentityInviteResponseDto: {
             id: string;
             email: string;
@@ -1749,29 +1933,6 @@ interface components {
             expired_count: number;
             revoked_count: number;
         };
-        CreateIdentityInviteDto: {
-            /** @description OAuth client ID — determines which app the invite links to. If omitted, uses Canopy hosted fallback. */
-            client_id?: string;
-            /**
-             * @description Optional. `activate` (default) creates a net-new identity OR — if an identity with this email already exists in the Account but has no active membership in this App — auto-derives an `add_to_app` invite that adds them to this App without touching their existing password. `password_reset` is the explicit admin-driven credential-rotation flow for an existing identity; it cannot carry a role/node assignment. The legacy `onboard` value is accepted and treated as `activate`.
-             * @enum {string}
-             */
-            intent?: "activate" | "password_reset" | "onboard";
-            email: string;
-            /** @description Required for `activate`. Ignored for `add_to_app` (the existing identity's name wins) and for `password_reset`. */
-            first_name?: string;
-            /** @description Required for `activate`. Ignored for `add_to_app` and `password_reset`. */
-            last_name?: string;
-            /** @description Role ID — required if node_id is provided */
-            role_id?: string;
-            /** @description Node ID — required if role_id is provided */
-            node_id?: string;
-            /**
-             * @description Whether Canopy should send the invite email. Set false to suppress delivery and handle it yourself — the API response includes accept_url with the tokenized link. Defaults to true.
-             * @default true
-             */
-            send_email: boolean;
-        };
         ApiIdentityInviteResponseDto: {
             id: string;
             email: string;
@@ -1800,6 +1961,29 @@ interface components {
             /** @description Tokenized URL the invitee would land on. Returned so callers that pass send_email=false can deliver it themselves. */
             accept_url: string;
         };
+        CreateIdentityInviteDto: {
+            /** @description OAuth client ID — determines which app the invite links to. If omitted, uses Canopy hosted fallback. */
+            client_id?: string;
+            /**
+             * @description Optional. `activate` (default) creates a net-new identity OR — if an identity with this email already exists in the Account but has no active membership in this App — auto-derives an `add_to_app` invite that adds them to this App without touching their existing password. `password_reset` is the explicit admin-driven credential-rotation flow for an existing identity; it cannot carry a role/node assignment. The legacy `onboard` value is accepted and treated as `activate`.
+             * @enum {string}
+             */
+            intent?: "activate" | "password_reset" | "onboard";
+            email: string;
+            /** @description Required for `activate`. Ignored for `add_to_app` (the existing identity's name wins) and for `password_reset`. */
+            first_name?: string;
+            /** @description Required for `activate`. Ignored for `add_to_app` and `password_reset`. */
+            last_name?: string;
+            /** @description Role ID — required if node_id is provided */
+            role_id?: string;
+            /** @description Node ID — required if role_id is provided */
+            node_id?: string;
+            /**
+             * @description Whether Canopy should send the invite email. Set false to suppress delivery and handle it yourself — the API response includes accept_url with the tokenized link. Defaults to true.
+             * @default true
+             */
+            send_email: boolean;
+        };
         BulkCreateIdentityInvitesDto: {
             invites: components["schemas"]["CreateIdentityInviteDto"][];
         };
@@ -1808,20 +1992,6 @@ interface components {
             /** @description Tokenized URL for the regenerated invite. Resend rotates the token, which invalidates any accept_url returned from the original create call. Self-delivery callers must replace the stored URL with this one. */
             accept_url: string;
         };
-        CreateNodeDto: {
-            /** @description Parent node ID (null for root) */
-            parent_node_id?: string;
-            /** @description Node type (org-defined, e.g. 'department', 'team') */
-            node_type: string;
-            /** @description Display name for the node */
-            name: string;
-            /** @description Optional free-text description shown under the node name */
-            description?: string;
-            /** @description URL-friendly slug (auto-generated if omitted) */
-            slug?: string;
-            /** @description Arbitrary metadata */
-            metadata?: Record<string, unknown>;
-        };
         NodeResponseDto: {
             id: string;
             application_id: string;
@@ -1840,6 +2010,20 @@ interface components {
             /** @description Optimistic-lock version. Send back as the `If-Match` header when updating, moving, or deleting to detect concurrent edits. */
             version: number;
         };
+        CreateNodeDto: {
+            /** @description Parent node ID (null for root) */
+            parent_node_id?: string;
+            /** @description Node type (org-defined, e.g. 'department', 'team') */
+            node_type: string;
+            /** @description Display name for the node */
+            name: string;
+            /** @description Optional free-text description shown under the node name */
+            description?: string;
+            /** @description URL-friendly slug (auto-generated if omitted) */
+            slug?: string;
+            /** @description Arbitrary metadata */
+            metadata?: Record<string, unknown>;
+        };
         HierarchyTreeNodeDto: {
             id: string;
             name: string;
@@ -1871,6 +2055,11 @@ interface components {
             tree: components["schemas"]["HierarchyTreeNodeDto"][];
             scope: components["schemas"]["HierarchyScopeDto"];
         };
+        NodeParentEdgeResponseDto: {
+            id: string;
+            /** @description Null for the root node, which has no parent. */
+            parent_node_id?: string | null;
+        };
         NodeAccessResponseDto: {
             id: string;
             application_id: string;
@@ -2074,6 +2263,44 @@ interface components {
             /** @description Whether this row should appear on a future end-user `My security activity` surface. Not consumed by current reads. */
             identity_visible: boolean;
         };
+        ExportJobDto: {
+            /** Format: uuid */
+            id: string;
+            /**
+             * @description `pending` (enqueued), `processing` (worker rendering), `completed` (file ready), or `failed` (see `error`).
+             * @enum {string}
+             */
+            status: "pending" | "processing" | "completed" | "failed";
+            /**
+             * @description The audit surface the export was taken from.
+             * @enum {string}
+             */
+            surface: "admin" | "identities";
+            /**
+             * @description Wire format of the rendered file.
+             * @enum {string}
+             */
+            format: "csv" | "ndjson";
+            /** Format: uuid */
+            application_id?: string | null;
+            /** Format: uuid */
+            environment_id?: string | null;
+            /** @description Rows written, set once the job completes. */
+            row_count?: number | null;
+            /** @description Failure detail, present only when `status` is `failed`. */
+            error?: string | null;
+            /** Format: date-time */
+            created_at: string;
+            /** Format: date-time */
+            completed_at?: string | null;
+            /**
+             * Format: date-time
+             * @description When the stored file + this record become eligible for sweep.
+             */
+            expires_at?: string | null;
+            /** @description Short-lived signed download URL. Present only on the single-job read of a completed job; `null` otherwise. */
+            download_url?: string | null;
+        };
         AuditExportQueryDto: {
             /**
              * Format: date-time
@@ -2116,49 +2343,11 @@ interface components {
             /** @description Full-text query against actor_label, resource_label (trigram), and metadata (GIN). */
             q?: string;
             /**
-             * @description Export wire format. `csv` for spreadsheet review (metadata folded into one JSON column); `ndjson` for SIEM ingestion (one JSON object per line, metadata nested). Defaults to `csv`.
-             * @default csv
-             * @enum {string}
-             */
-            format: "csv" | "ndjson";
-        };
-        ExportJobDto: {
-            /** Format: uuid */
-            id: string;
-            /**
-             * @description `pending` (enqueued), `processing` (worker rendering), `completed` (file ready), or `failed` (see `error`).
-             * @enum {string}
-             */
-            status: "pending" | "processing" | "completed" | "failed";
-            /**
-             * @description The audit surface the export was taken from.
-             * @enum {string}
-             */
-            surface: "admin" | "identities";
-            /**
-             * @description Wire format of the rendered file.
+             * @description Export wire format. `csv` for spreadsheet review (metadata folded into one JSON column); `ndjson` for SIEM ingestion (one JSON object per line, metadata nested). Defaults to `csv`.
+             * @default csv
              * @enum {string}
              */
             format: "csv" | "ndjson";
-            /** Format: uuid */
-            application_id?: string | null;
-            /** Format: uuid */
-            environment_id?: string | null;
-            /** @description Rows written, set once the job completes. */
-            row_count?: number | null;
-            /** @description Failure detail, present only when `status` is `failed`. */
-            error?: string | null;
-            /** Format: date-time */
-            created_at: string;
-            /** Format: date-time */
-            completed_at?: string | null;
-            /**
-             * Format: date-time
-             * @description When the stored file + this record become eligible for sweep.
-             */
-            expires_at?: string | null;
-            /** @description Short-lived signed download URL. Present only on the single-job read of a completed job; `null` otherwise. */
-            download_url?: string | null;
         };
         AuditLogDetailResponseDto: {
             id: string;
@@ -2252,11 +2441,6 @@ interface components {
             /** @description Node type used when the root node is auto-created. Must be one of `node_types`. */
             root_node_type: string;
         };
-        CreateWebhookDto: {
-            url: string;
-            event_types: string[];
-            description?: string;
-        };
         WebhookCreatedResponseDto: {
             id: string;
             /** @enum {string} */
@@ -2270,6 +2454,11 @@ interface components {
             /** @description HMAC secret — only shown once on creation */
             secret: string;
         };
+        CreateWebhookDto: {
+            url: string;
+            event_types: string[];
+            description?: string;
+        };
         WebhookResponseDto: {
             id: string;
             /** @enum {string} */
@@ -2305,21 +2494,6 @@ interface components {
             description?: string | null;
             is_active?: boolean;
         };
-        CreateApiKeyDto: {
-            /** @description API key name */
-            name: string;
-            /** @description API key description */
-            description?: string;
-            /**
-             * @description Required. `scoped` enforces the `scopes` array on every authorization check (deny if the requested permission isn't listed). `full_access` bypasses RBAC entirely within the key's Application — every permission is granted. Pick `scoped` whenever possible; `full_access` should be a deliberate choice (use cases: bootstrap automation, trusted backend services that legitimately need App-wide access). `scoped` requires a non-empty `scopes` array; `full_access` forbids `scopes`.
-             * @enum {string}
-             */
-            access_mode: "scoped" | "full_access";
-            /** @description Permission scopes this key is authorized for. Required and must be non-empty when `access_mode` is `scoped`. Must be omitted when `access_mode` is `full_access`. */
-            scopes?: string[];
-            /** @description Expiration date (ISO 8601). Omit for no expiration. */
-            expires_at?: string;
-        };
         ApiKeyCreatedResponseDto: {
             id: string;
             name: string;
@@ -2338,6 +2512,21 @@ interface components {
             /** Format: date-time */
             created_at: string;
         };
+        CreateApiKeyDto: {
+            /** @description API key name */
+            name: string;
+            /** @description API key description */
+            description?: string;
+            /**
+             * @description Required. `scoped` enforces the `scopes` array on every authorization check (deny if the requested permission isn't listed). `full_access` bypasses RBAC entirely within the key's Application — every permission is granted. Pick `scoped` whenever possible; `full_access` should be a deliberate choice (use cases: bootstrap automation, trusted backend services that legitimately need App-wide access). `scoped` requires a non-empty `scopes` array; `full_access` forbids `scopes`.
+             * @enum {string}
+             */
+            access_mode: "scoped" | "full_access";
+            /** @description Permission scopes this key is authorized for. Required and must be non-empty when `access_mode` is `scoped`. Must be omitted when `access_mode` is `full_access`. */
+            scopes?: string[];
+            /** @description Expiration date (ISO 8601). Omit for no expiration. */
+            expires_at?: string;
+        };
         ApiKeyResponseDto: {
             id: string;
             client_id: string;
@@ -2498,7 +2687,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["PermissionResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["PermissionResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -2562,7 +2753,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["PermissionResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["PermissionResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -2721,7 +2914,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["PermissionResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["PermissionResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -2789,6 +2984,93 @@ interface operations {
             };
         };
     };
+    ApiPermissionsController_getPermissionUsage: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Granting roles and identity reach returned */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["PermissionUsageDto"];
+                    };
+                };
+            };
+            /** @description Invalid or expired token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": {
+                     *         "statusCode": 401,
+                     *         "code": null,
+                     *         "message": "Invalid or expired token",
+                     *         "timestamp": "2026-04-20T12:00:00.000Z",
+                     *         "path": "/api/v1/permissions",
+                     *         "method": "GET"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorResponseDto"];
+                };
+            };
+            /** @description This token is not authorized for this endpoint (wrong principal type — e.g., admin token on identity-only endpoint, or vice versa) */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": {
+                     *         "statusCode": 403,
+                     *         "code": null,
+                     *         "message": "This token is not authorized for this endpoint (wrong principal type — e.g., admin token on identity-only endpoint, or vice versa)",
+                     *         "timestamp": "2026-04-20T12:00:00.000Z",
+                     *         "path": "/api/v1/permissions",
+                     *         "method": "GET"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorResponseDto"];
+                };
+            };
+            /** @description No permission with that id exists in this Environment */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": {
+                     *         "statusCode": 404,
+                     *         "code": null,
+                     *         "message": "No permission with that id exists in this Environment",
+                     *         "timestamp": "2026-04-20T12:00:00.000Z",
+                     *         "path": "/api/v1/permissions/{id}/usage",
+                     *         "method": "GET"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorResponseDto"];
+                };
+            };
+        };
+    };
     ApiPermissionsController_evaluate: {
         parameters: {
             query?: never;
@@ -2808,7 +3090,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["EvaluateResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["EvaluateResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -2942,7 +3226,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["PermissionTraceDto"];
+                    "application/json": {
+                        data: components["schemas"]["PermissionTraceDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -3105,7 +3391,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["IdentityResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["IdentityResponseDto"];
+                    };
                 };
             };
             /** @description Password rejected — appeared in a known data breach (HaveIBeenPwned check) */
@@ -3289,7 +3577,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["IdentitiesSummaryDto"];
+                    "application/json": {
+                        data: components["schemas"]["IdentitiesSummaryDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -3477,7 +3767,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["IdentityResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["IdentityResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -3649,7 +3941,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["IdentityResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["IdentityResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -3734,7 +4028,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["IdentityDetailResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["IdentityDetailResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -3819,7 +4115,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["MessageResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["MessageResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -3904,7 +4202,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["MessageResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["MessageResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -4263,7 +4563,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["AccountIdentityMfaResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["AccountIdentityMfaResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -4431,7 +4733,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["IdentityAuthStateResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["IdentityAuthStateResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -4671,14 +4975,101 @@ interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Effective App-wide permissions returned */
+            /** @description Effective App-wide permissions returned */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        items: string[];
+                    };
+                };
+            };
+            /** @description Invalid or expired token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": {
+                     *         "statusCode": 401,
+                     *         "code": null,
+                     *         "message": "Invalid or expired token",
+                     *         "timestamp": "2026-04-20T12:00:00.000Z",
+                     *         "path": "/api/v1/identities",
+                     *         "method": "GET"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorResponseDto"];
+                };
+            };
+            /** @description This token is not authorized for this endpoint (wrong principal type — e.g., admin token on identity-only endpoint, or vice versa) */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": {
+                     *         "statusCode": 403,
+                     *         "code": null,
+                     *         "message": "This token is not authorized for this endpoint (wrong principal type — e.g., admin token on identity-only endpoint, or vice versa)",
+                     *         "timestamp": "2026-04-20T12:00:00.000Z",
+                     *         "path": "/api/v1/identities",
+                     *         "method": "GET"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorResponseDto"];
+                };
+            };
+            /** @description Identity not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": {
+                     *         "statusCode": 404,
+                     *         "code": null,
+                     *         "message": "Identity not found",
+                     *         "timestamp": "2026-04-20T12:00:00.000Z",
+                     *         "path": "/api/v1/identities/{id}/permissions",
+                     *         "method": "GET"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorResponseDto"];
+                };
+            };
+        };
+    };
+    ApiIdentitiesController_getIdentityGrants: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Grant map returned */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
                     "application/json": {
-                        items: string[];
+                        items: components["schemas"]["IdentityGrantResponseDto"][];
                     };
                 };
             };
@@ -4724,6 +5115,27 @@ interface operations {
                     "application/json": components["schemas"]["ErrorResponseDto"];
                 };
             };
+            /** @description Identity not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": {
+                     *         "statusCode": 404,
+                     *         "code": null,
+                     *         "message": "Identity not found",
+                     *         "timestamp": "2026-04-20T12:00:00.000Z",
+                     *         "path": "/api/v1/identities/{id}/grants",
+                     *         "method": "GET"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorResponseDto"];
+                };
+            };
         };
     };
     ApiIdentityInvitesController_listInvites: {
@@ -4825,7 +5237,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ApiIdentityInviteResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["ApiIdentityInviteResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -4887,7 +5301,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["IdentityInvitesSummaryDto"];
+                    "application/json": {
+                        data: components["schemas"]["IdentityInvitesSummaryDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -5075,7 +5491,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ApiIdentityInviteResendResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["ApiIdentityInviteResendResponseDto"];
+                    };
                 };
             };
             /** @description Invite is no longer pending */
@@ -5271,7 +5689,10 @@ interface operations {
     ApiNodesController_listNodes: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /** @description An `ETag` from a previous response. Answers `304 Not Modified` when the hierarchy has not changed since, so a client holding a cached tree can revalidate on a short interval without re-reading it. */
+                "If-None-Match"?: string;
+            };
             path?: never;
             cookie?: never;
         };
@@ -5283,8 +5704,17 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ScopedHierarchyTreeResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["ScopedHierarchyTreeResponseDto"];
+                    };
+                };
+            };
+            /** @description The hierarchy is unchanged since the supplied `ETag`. No body; keep using the cached tree. */
+            304: {
+                headers: {
+                    [name: string]: unknown;
                 };
+                content?: never;
             };
             /** @description Invalid or expired token */
             401: {
@@ -5349,7 +5779,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["NodeResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["NodeResponseDto"];
+                    };
                 };
             };
             /** @description Invalid parent-child relationship */
@@ -5438,6 +5870,80 @@ interface operations {
             };
         };
     };
+    ApiNodesController_listNodeParents: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description An `ETag` from a previous response. Answers `304 Not Modified` when the hierarchy has not changed since, so a client holding a cached tree can revalidate on a short interval without re-reading it. */
+                "If-None-Match"?: string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Parent edges returned */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        items: components["schemas"]["NodeParentEdgeResponseDto"][];
+                    };
+                };
+            };
+            /** @description The hierarchy is unchanged since the supplied `ETag`. No body; keep using the cached tree. */
+            304: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Invalid or expired token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": {
+                     *         "statusCode": 401,
+                     *         "code": null,
+                     *         "message": "Invalid or expired token",
+                     *         "timestamp": "2026-04-20T12:00:00.000Z",
+                     *         "path": "/api/v1/nodes",
+                     *         "method": "GET"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorResponseDto"];
+                };
+            };
+            /** @description This token is not authorized for this endpoint (wrong principal type — e.g., admin token on identity-only endpoint, or vice versa) */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": {
+                     *         "statusCode": 403,
+                     *         "code": null,
+                     *         "message": "This token is not authorized for this endpoint (wrong principal type — e.g., admin token on identity-only endpoint, or vice versa)",
+                     *         "timestamp": "2026-04-20T12:00:00.000Z",
+                     *         "path": "/api/v1/nodes",
+                     *         "method": "GET"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorResponseDto"];
+                };
+            };
+        };
+    };
     ApiNodesController_getNode: {
         parameters: {
             query?: never;
@@ -5455,7 +5961,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["NodeAccessResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["NodeAccessResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -5656,7 +6164,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["NodeResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["NodeResponseDto"];
+                    };
                 };
             };
             /** @description Invalid parent-child relationship */
@@ -5783,7 +6293,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["HierarchyTreeNodeDto"];
+                    "application/json": {
+                        data: components["schemas"]["HierarchyTreeNodeDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -5987,7 +6499,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["NodeResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["NodeResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -6200,7 +6714,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["NodeIdentitiesSummaryDto"];
+                    "application/json": {
+                        data: components["schemas"]["NodeIdentitiesSummaryDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -6354,7 +6870,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["RoleResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["RoleResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -6439,7 +6957,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["RoleResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["RoleResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -6640,7 +7160,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["RoleResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["RoleResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -6837,7 +7359,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["MessageResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["MessageResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -7002,7 +7526,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["AssignmentsSummaryDto"];
+                    "application/json": {
+                        data: components["schemas"]["AssignmentsSummaryDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -7068,7 +7594,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["AssignmentResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["AssignmentResponseDto"];
+                    };
                 };
             };
             /** @description System roles cannot be assigned to identities — they are reserved for platform administration */
@@ -7261,7 +7789,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["AssignmentResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["AssignmentResponseDto"];
+                    };
                 };
             };
             /** @description System roles cannot be assigned to identities — they are reserved for platform administration */
@@ -7433,7 +7963,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["MessageResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["MessageResponseDto"];
+                    };
                 };
             };
             /** @description System roles cannot be assigned to identities — they are reserved for platform administration */
@@ -7821,7 +8353,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ExportJobDto"];
+                    "application/json": {
+                        data: components["schemas"]["ExportJobDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -7885,7 +8419,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ExportJobDto"];
+                    "application/json": {
+                        data: components["schemas"]["ExportJobDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -8053,7 +8589,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["AuditLogDetailResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["AuditLogDetailResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -8230,7 +8768,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["HierarchySchemaResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["HierarchySchemaResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -8300,7 +8840,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["HierarchySchemaResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["HierarchySchemaResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -8463,7 +9005,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["WebhookCreatedResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["WebhookCreatedResponseDto"];
+                    };
                 };
             };
             /** @description One or more event types are not supported */
@@ -8711,7 +9255,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["WebhookResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["WebhookResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -8883,7 +9429,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["WebhookResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["WebhookResponseDto"];
+                    };
                 };
             };
             /** @description One or more event types are not supported */
@@ -9067,7 +9615,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ApiKeyCreatedResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["ApiKeyCreatedResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -9218,7 +9768,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ApiKeyResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["ApiKeyResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -9303,7 +9855,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ApiKeyCreatedResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["ApiKeyCreatedResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -9436,6 +9990,27 @@ type QueryParams<Id extends OperationId> = operations[Id] extends {
 } ? NonNullable<Query> : Record<string, never>;
 /** Shorthand for a named schema, e.g. `Schema<"EvaluateResponseDto">`. */
 type Schema<Name extends keyof components["schemas"]> = components["schemas"][Name];
+/**
+ * Optimistic concurrency, on the operations whose spec declares `If-Match`.
+ *
+ * Pass the `version` you read off the resource. If someone else has changed it
+ * since, the API answers 409 rather than letting the write silently clobber
+ * theirs — so this is how a read-modify-write is made safe.
+ */
+interface ConcurrencyOptions {
+    ifMatch?: string;
+}
+/**
+ * The `If-Match` header for a call that supports it, shaped to be spread into
+ * `RequestOptions`.
+ *
+ * Spreadable rather than returning `headers: undefined`, which
+ * `exactOptionalPropertyTypes` rejects — an absent property and one explicitly
+ * set to undefined are not the same thing here.
+ */
+declare function withConcurrency(options?: ConcurrencyOptions): {
+    headers: Record<string, string>;
+} | Record<string, never>;
 
 /**
  * Role grants: which identity holds which role, at which node.
@@ -9490,8 +10065,18 @@ declare class Identities {
      */
     deactivate(id: string): Promise<ResponseBody<"ApiIdentitiesController_deactivateIdentity">>;
     activate(id: string): Promise<ResponseBody<"ApiIdentitiesController_activateIdentity">>;
-    /** Every role this identity holds, and where. */
-    assignments(id: string): Promise<ResponseBody<"ApiIdentitiesController_getIdentityAssignments">>;
+    /**
+     * Every role this identity holds, and where — across all pages.
+     *
+     * Paginated (20 per page by default), so this returns a `Paginator` rather
+     * than one response. Reading a single page here would under-report what an
+     * identity can do, which is the dangerous direction to be wrong in.
+     *
+     * ```ts
+     * for await (const assignment of canopy.identities.assignments(id)) { … }
+     * ```
+     */
+    assignments(id: string, query?: QueryParams<"ApiIdentitiesController_getIdentityAssignments">): Paginator<IdentityAssignmentItem>;
     /**
      * The permissions this identity effectively holds, inheritance resolved.
      *
@@ -9502,6 +10087,8 @@ declare class Identities {
     permissions(id: string): Promise<ResponseBody<"ApiIdentitiesController_getIdentityPermissions">>;
 }
 type IdentityItem = ItemOf$2<ResponseBody<"ApiIdentitiesController_listIdentities">>;
+/** One role grant from an identity's assignments collection. */
+type IdentityAssignmentItem = ItemOf$2<ResponseBody<"ApiIdentitiesController_getIdentityAssignments">>;
 type ItemOf$2<T> = T extends {
     items: (infer Item)[];
 } ? Item : never;
@@ -9524,28 +10111,37 @@ declare class Permissions {
      * `effective_node_id: null` — that answer must never be used to guard a
      * resource that belongs to a specific node, which is why the scope is a
      * required field rather than a default.
+     *
+     * This runs on the request path, so it is the call most worth passing
+     * `signal` and a tight `timeoutMs` to: without them a slow answer here holds
+     * an inbound request open for the client-wide deadline on every attempt.
      */
-    evaluate(input: RequestBody<"ApiPermissionsController_evaluate">): Promise<ResponseBody<"ApiPermissionsController_evaluate">>;
+    evaluate(input: RequestBody<"ApiPermissionsController_evaluate">, options?: CallOptions): Promise<ResponseBody<"ApiPermissionsController_evaluate">>;
     /**
      * Evaluate many decisions in one round trip.
      *
      * Prefer this to a loop over `evaluate` when rendering a screen: the checks
      * are answered together instead of paying request latency for each.
      */
-    evaluateBulk(input: RequestBody<"ApiPermissionsController_evaluateBulk">): Promise<ResponseBody<"ApiPermissionsController_evaluateBulk">>;
+    evaluateBulk(input: RequestBody<"ApiPermissionsController_evaluateBulk">, options?: CallOptions): Promise<ResponseBody<"ApiPermissionsController_evaluateBulk">>;
     /**
      * The same decision with its reasoning — which role granted it, which node
      * it was inherited from. For debugging an unexpected allow or deny, not for
      * the enforcement path.
      */
-    explain(input: RequestBody<"ApiPermissionsController_explain">): Promise<ResponseBody<"ApiPermissionsController_explain">>;
+    explain(input: RequestBody<"ApiPermissionsController_explain">, options?: CallOptions): Promise<ResponseBody<"ApiPermissionsController_explain">>;
     /** Every permission in the Environment, page by page. */
     list(query?: QueryParams<"ApiPermissionsController_listPermissions">): Paginator<PermissionItem>;
     get(id: string): Promise<ResponseBody<"ApiPermissionsController_getPermission">>;
     /** Define permissions. The request takes a batch, not a single key. */
     create(input: RequestBody<"ApiPermissionsController_createPermissions">): Promise<ResponseBody<"ApiPermissionsController_createPermissions">>;
-    update(id: string, input: RequestBody<"ApiPermissionsController_updatePermission">): Promise<ResponseBody<"ApiPermissionsController_updatePermission">>;
-    delete(id: string): Promise<void>;
+    /**
+     * Pass `ifMatch` with the permission's current `version` to make a
+     * read-modify-write safe — a concurrent edit answers 409 instead of being
+     * silently overwritten.
+     */
+    update(id: string, input: RequestBody<"ApiPermissionsController_updatePermission">, options?: ConcurrencyOptions): Promise<ResponseBody<"ApiPermissionsController_updatePermission">>;
+    delete(id: string, options?: ConcurrencyOptions): Promise<void>;
 }
 /**
  * One item from the permissions collection.
@@ -9565,8 +10161,13 @@ declare class Roles {
     list(query?: QueryParams<"ApiRolesController_listRoles">): Paginator<RoleItem>;
     get(id: string): Promise<ResponseBody<"ApiRolesController_getRole">>;
     create(input: RequestBody<"ApiRolesController_createRole">): Promise<ResponseBody<"ApiRolesController_createRole">>;
-    update(id: string, input: RequestBody<"ApiRolesController_updateRole">): Promise<ResponseBody<"ApiRolesController_updateRole">>;
-    delete(id: string): Promise<void>;
+    /**
+     * Pass `ifMatch` with the role's current `version` to make a
+     * read-modify-write safe — a concurrent edit answers 409 instead of being
+     * silently overwritten.
+     */
+    update(id: string, input: RequestBody<"ApiRolesController_updateRole">, options?: ConcurrencyOptions): Promise<ResponseBody<"ApiRolesController_updateRole">>;
+    delete(id: string, options?: ConcurrencyOptions): Promise<void>;
     permissions(id: string): Promise<ResponseBody<"ApiRolesController_getRolePermissions">>;
     /**
      * Replaces the role's permissions wholesale — this is a PUT, so anything
@@ -9608,13 +10209,129 @@ declare class Canopy {
     constructor(options: CanopyClientOptions);
 }
 
+interface LocalAuthorizerOptions {
+    /**
+     * How long grant roots and the hierarchy are reused, in milliseconds.
+     * Defaults to 60s.
+     *
+     * This is a staleness budget, not a performance dial. Shortening it makes
+     * revocation take effect sooner and costs more calls — and below the gap
+     * between a user's requests it stops saving anything at all, because every
+     * request finds the cache expired and refetches. Human-paced traffic has
+     * multi-second gaps, so a value of a few seconds can cost full price for no
+     * benefit.
+     *
+     * **`0` disables caching**, reading fresh on every check. That is the escape
+     * for a caller who cannot accept a stale allow at all — it costs a round trip
+     * per request, which is what this class exists to avoid, so reach for it
+     * knowingly rather than as a default.
+     */
+    ttlMs?: number;
+    /**
+     * Per-attempt deadline for the reads this class makes.
+     *
+     * A cache hit costs nothing, but a miss happens on the request path and
+     * holds an inbound request open exactly as a per-request check used to — so
+     * the bound still matters, it just applies far less often.
+     */
+    timeoutMs?: number;
+    /** Retries for those reads. */
+    maxRetries?: number;
+    /** Injectable clock, for tests. */
+    now?: () => number;
+}
+interface LocalAuthorizationQuery {
+    identity_id: string;
+    permission: string;
+    /** Defaults to `node`, which is the strict question. */
+    scope?: "node" | "app_wide";
+    node_id?: string;
+}
+interface LocalAuthorizerStats {
+    /** Calls made to read an identity's grant roots. */
+    grantFetches: number;
+    /** Calls made to read the hierarchy, including revalidations. */
+    treeRequests: number;
+    /** Revalidations the server answered `304`, so no tree was transferred. */
+    treeNotModified: number;
+}
+declare class LocalAuthorizer {
+    private readonly client;
+    private readonly ttlMs;
+    private readonly now;
+    private readonly readOptions;
+    private readonly grants;
+    private tree;
+    /**
+     * In-flight reads, so concurrent requests for the same thing share one call.
+     *
+     * Without this a cold start under load fans out: a hundred simultaneous
+     * requests for one identity would each miss the cache and each fetch, which
+     * is the per-request traffic this class exists to remove, concentrated into
+     * the worst possible moment.
+     */
+    private readonly pendingGrants;
+    private pendingTree;
+    private stats;
+    constructor(client: CanopyClient, options?: LocalAuthorizerOptions);
+    /**
+     * Whether the identity holds the permission.
+     *
+     * Shaped like the API's own evaluate so a caller can swap one for the other.
+     * A `node` check with no node is a denial rather than an error: a request
+     * whose subject cannot be established is exactly the one that must not pass.
+     */
+    evaluate(query: LocalAuthorizationQuery, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        allowed: boolean;
+    }>;
+    private decide;
+    /** Counters for observability — how much traffic the cache is actually saving. */
+    snapshot(): LocalAuthorizerStats;
+    /**
+     * Drop what is held so the next evaluate refetches.
+     *
+     * With an `identityId`, only that identity's grants are dropped — the
+     * cached hierarchy and every other identity's entries stay warm. This is
+     * the shape an assignment webhook wants: the event names the identity
+     * whose authority moved, and nothing else needs to pay a refetch for it.
+     *
+     * With no argument, everything goes: grants and the hierarchy tree. Not
+     * needed in normal operation, where entries expire on their own; useful in
+     * tests and after a change whose reach you cannot name (a role's
+     * permissions edited, a node moved).
+     *
+     * Multi-instance honesty: an invalidation reaches THIS process only. A
+     * webhook lands on one instance behind a load balancer; the others serve
+     * their cached grants until their own TTL expires. Unless the app fans the
+     * event out over its own pub/sub, the fleet-wide revocation guarantee is
+     * the TTL, and webhook-driven invalidation is a latency optimization on
+     * top of it — size the TTL to the revocation latency you can promise.
+     */
+    invalidate(identityId?: string): void;
+    /** Climb from `nodeId` and look for a grant root among its ancestors. */
+    private holdsAtNode;
+    private grantRootsFor;
+    private fetchGrantRoots;
+    private parents;
+    /**
+     * Revalidate rather than re-read. The hierarchy is the expensive half and
+     * the one that changes least, so the common case is a `304` and no transfer
+     * at all — the tree stays in memory and only its expiry moves.
+     */
+    private fetchTree;
+}
+
 /**
  * Everything this client throws.
  *
- * Two classes, because callers act on the distinction: `CanopyError` means the
- * API answered and said no, `CanopyConnectionError` means it never answered.
- * The first is a decision you may need to surface to a user; the second is
- * usually worth retrying or alerting on.
+ * Three classes, because callers act on the distinction: `CanopyError` means
+ * the API answered and said no, `CanopyConnectionError` means it never
+ * answered, and `CanopyTokenError` means a token failed local verification
+ * without anything being asked of the API at all. The first is a decision you
+ * may need to surface to a user; the second is usually worth retrying or
+ * alerting on; the third is a 401 for the caller who presented the token.
  */
 /** The `error` object inside Canopy's error envelope. */
 interface CanopyErrorBody {
@@ -9651,18 +10368,29 @@ declare class CanopyError extends Error {
         method: string;
         path: string;
     };
+    /**
+     * How long to wait before retrying, in milliseconds, when the server said so
+     * via `Retry-After` — populated on a 429, and on any other response that
+     * carries the header. Undefined when the server gave no guidance.
+     */
+    readonly retryAfterMs: number | undefined;
     constructor(body: CanopyErrorBody, request: {
         method: string;
         path: string;
-    });
+    }, retryAfterMs?: number);
     /** A 429. `retryAfterMs` is populated when the server said how long to wait. */
     get isRateLimited(): boolean;
     /** 401 or 403 — the credential is wrong or not permitted here. */
     get isAuthFailure(): boolean;
 }
 /**
- * The request never produced a response — DNS failure, connection reset,
- * timeout, or an aborted signal.
+ * The request never produced a response — DNS failure, connection reset, or a
+ * timeout.
+ *
+ * Not this: a caller's own cancellation. Aborting the `signal` passed to a
+ * request rejects with that abort (`AbortError`, or whatever `signal.reason`
+ * holds) and is never retried, because the caller stopping is an intent rather
+ * than a failure to report.
  *
  * Kept separate from `CanopyError` because there is no status code and no
  * server opinion to report: nothing is known about whether the operation
@@ -9681,8 +10409,202 @@ declare class CanopyConnectionError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * A token failed verification.
+ *
+ * Separate from `CanopyError` because nothing was asked of the API: the token
+ * was checked here, against keys already held. There is no status code to
+ * report and no server opinion to relay — the decision was local, which is the
+ * whole point of verifying a signature rather than calling an endpoint.
+ *
+ * Branch on `code`; it follows the same dot-notation contract as the API's own
+ * codes. Every one of them means the same thing to an HTTP caller — 401 — so
+ * the code is for your logs and your tests, not usually for the response.
+ */
+declare class CanopyTokenError extends Error {
+    readonly name = "CanopyTokenError";
+    /**
+     * One of:
+     *
+     * - `token.malformed` — not a JWS, or a segment would not decode
+     * - `token.unsupported_algorithm` — not RS256; Canopy issues only RS256
+     * - `token.key_not_found` — no published key matches the token's `kid`
+     * - `token.jwks_unavailable` — the key set could not be fetched or parsed
+     * - `token.signature_invalid` — signature does not match the signing key
+     * - `token.expired` / `token.not_yet_valid` — outside its validity window
+     * - `token.issuer_mismatch` — `iss` is not the configured issuer
+     * - `token.audience_mismatch` — `aud` does not include the configured audience
+     * - `token.audience_unverified` — token has an `aud` but none was configured
+     * - `token.preauth_not_allowed` — a pre-auth token, which grants no access
+     */
+    readonly code: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The local authorizer could not answer, and must not pretend otherwise.
+ *
+ * Distinct from a denial. It is raised when the data a decision needs is not
+ * merely absent but *unreadable* — most often a credential that cannot read the
+ * hierarchy, which comes back as an empty tree rather than an error. Denying
+ * there would be a silent, total false-deny on every node-scoped route while
+ * every response still looked healthy.
+ *
+ * No retry fixes it, so callers should treat it as a misconfiguration rather
+ * than an outage.
+ */
+declare class CanopyAuthorizerError extends Error {
+    readonly name = "CanopyAuthorizerError";
+    readonly code: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare function isCanopyAuthorizerError(error: unknown): error is CanopyAuthorizerError;
 /** Narrowing helper that survives bundling and duplicate copies of the package. */
 declare function isCanopyError(error: unknown): error is CanopyError;
 declare function isCanopyConnectionError(error: unknown): error is CanopyConnectionError;
+declare function isCanopyTokenError(error: unknown): error is CanopyTokenError;
+
+interface TokenVerifierOptions {
+    /**
+     * The issuer whose tokens are accepted, matched against `iss` exactly.
+     * Defaults to Canopy's hosted issuer; set it for a self-hosted instance.
+     *
+     * Safe to default because it fails closed: pointed at the wrong issuer, a
+     * token is rejected rather than accepted.
+     */
+    issuer?: string;
+    /**
+     * Required audience, matched against `aud`.
+     *
+     * Hosted Login (OAuth) tokens carry `aud` — your client id — and Direct API
+     * identity tokens do not. Verifying an OAuth token without setting this
+     * throws rather than ignoring the claim, because `aud` is what stops a token
+     * minted for one client being replayed at another.
+     */
+    audience?: string;
+    /** Where the signing keys live. Defaults to `${issuer}/.well-known/jwks.json`. */
+    jwksUri?: string;
+    /** How long a fetched key set is reused. Defaults to 10 minutes. */
+    jwksCacheMaxAgeMs?: number;
+    /** Floor between refetches provoked by an unknown `kid`. Defaults to 30s. */
+    jwksMinRefetchIntervalMs?: number;
+    /** Leeway on `exp` and `nbf`, in seconds. Defaults to 60. */
+    clockToleranceSec?: number;
+    /**
+     * Accept pre-auth tokens. Defaults to `false`, and should stay false unless
+     * you are building an account picker.
+     *
+     * A pre-auth token is a genuine, correctly-signed Canopy token issued
+     * partway through a multi-account login: the person proved their password
+     * but has not yet chosen an Account, so the token carries no Account context
+     * and grants nothing. Accepting one as a session is a privilege escalation,
+     * and it is the failure a hand-rolled verifier is most likely to miss —
+     * every signature check passes.
+     */
+    allowPreAuthTokens?: boolean;
+    /**
+     * Deadline for a single JWKS read, in milliseconds. Defaults to 5s.
+     *
+     * Without one, an issuer that accepts a connection and then never answers
+     * holds every inbound request that needs a key — the verification sits on the
+     * request path, so an unbounded read there is an unbounded request.
+     */
+    jwksTimeoutMs?: number;
+    /** Injectable for tests and for runtimes with a non-global fetch. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * The claims Canopy puts in an access token.
+ *
+ * Named claims are the ones the API guarantees; the index signature keeps
+ * anything added later reachable without a version bump.
+ */
+interface CanopyTokenClaims {
+    /** The identity or user this token acts as. */
+    sub: string;
+    /** Which kind of principal `sub` is. */
+    type: "user" | "identity" | "api_key" | "platform";
+    iss: string;
+    exp: number;
+    iat?: number;
+    nbf?: number;
+    aud?: string | string[];
+    account_id?: string;
+    application_id?: string;
+    /** Identity tokens carry this; admin tokens deliberately omit it. */
+    environment_id?: string;
+    account_slug?: string;
+    application_slug?: string;
+    environment_slug?: string;
+    /** Present only on a pre-auth token — see `allowPreAuthTokens`. */
+    token_type?: "preauth";
+    console_access?: "granted" | "none";
+    /** Emitted only when the `permissions` OAuth scope was granted. */
+    permissions?: string[];
+    /** True when `permissions` was truncated; query the API for the full set. */
+    permissions_overflow?: boolean;
+    [claim: string]: unknown;
+}
+declare class TokenVerifier {
+    private readonly issuer;
+    private readonly audience;
+    private readonly jwksUri;
+    private readonly jwksCacheMaxAgeMs;
+    private readonly jwksMinRefetchIntervalMs;
+    private readonly jwksTimeoutMs;
+    private readonly clockToleranceSec;
+    private readonly allowPreAuthTokens;
+    private readonly fetchImpl;
+    /** Imported keys by `kid`, so a repeat verification skips the import cost. */
+    private keys;
+    private keysFetchedAt;
+    private lastFetchAttemptAt;
+    /** In-flight fetch, so a burst of requests triggers one call, not N. */
+    private inFlight;
+    constructor(options?: TokenVerifierOptions);
+    /**
+     * Verify a token and return its claims. Throws {@link CanopyTokenError} on
+     * anything short of a full pass — branch on `error.code`.
+     *
+     * Order matters: the signature is checked before any claim is believed, so
+     * nothing downstream ever reads an unverified payload.
+     */
+    verify(token: string): Promise<CanopyTokenClaims>;
+    /** Everything checked after the signature is known good. */
+    private assertClaims;
+    /**
+     * `aud` is checked when either side mentions it.
+     *
+     * The case worth stating: a token carries `aud` but the verifier was not
+     * configured with one. That is not "no audience to check" — it is an OAuth
+     * token being verified by something that never said which client it is, and
+     * ignoring it would accept a token minted for a different client. So it
+     * throws and names the option.
+     */
+    private assertAudience;
+    /**
+     * The signing key for a `kid`, fetching the key set when it is stale or when
+     * the `kid` is unknown — the latter is how key rotation is picked up
+     * mid-process, bounded by `jwksMinRefetchIntervalMs`.
+     */
+    private resolveKey;
+    /**
+     * Whether to await a key-set refresh.
+     *
+     * Two ways to qualify, and the first matters as much as the second. A read
+     * already in flight is joined regardless of the floor: it costs no extra
+     * outbound request, and it is what lets a concurrent burst share one fetch
+     * instead of one caller winning and the rest being turned away.
+     *
+     * Otherwise the floor applies — the same one for every refetch path, so they
+     * cannot drift into having different amplification properties.
+     */
+    private shouldRefresh;
+    private refreshKeys;
+    private fetchKeys;
+}
 
-export { type AssignmentItem, Assignments, Canopy, CanopyClient, type CanopyClientOptions, CanopyConnectionError, CanopyError, type CanopyErrorBody, type Collection, type CursorPagination, Identities, type IdentityItem, type OffsetPagination, type OperationId, type PageFetcher, type PageParams, type PaginateOptions, type Pagination, Paginator, type PartialSuccess, type PermissionItem, Permissions, type QueryParams, type RequestBody, type RequestOptions, type ResponseBody, type RoleItem, Roles, type Schema, type components, isCanopyConnectionError, isCanopyError, isCursorPagination, type operations, paginate, type paths };
+export { type AssignmentItem, Assignments, type CallOptions, Canopy, CanopyAuthorizerError, CanopyClient, type CanopyClientOptions, CanopyConnectionError, CanopyError, type CanopyErrorBody, type CanopyTokenClaims, CanopyTokenError, type Collection, type ConcurrencyOptions, type ConditionalResult, type CursorPagination, Identities, type IdentityAssignmentItem, type IdentityItem, type LocalAuthorizationQuery, LocalAuthorizer, type LocalAuthorizerOptions, type LocalAuthorizerStats, type OffsetPagination, type OperationId, type PageFetcher, type PageParams, type PaginateOptions, type Pagination, Paginator, type PartialSuccess, type PermissionItem, Permissions, type QueryParams, type RequestBody, type RequestOptions, type ResponseBody, type RoleItem, Roles, type Schema, TokenVerifier, type TokenVerifierOptions, type components, isCanopyAuthorizerError, isCanopyConnectionError, isCanopyError, isCanopyTokenError, isCursorPagination, type operations, paginate, type paths, withConcurrency };