@canopy-io/node 0.7.2 → 0.9.0

package/dist/index.d.ts

@@ -378,7 +378,7 @@ interface paths {
         put?: never;
         /**
          * Bulk evaluate authorization
-         * @description Evaluates many permission checks in a single request, returning a `{ items }` array of decisions in the same order as the input `checks`, each with the same shape as the single evaluate endpoint. Every check is resolved independently against its own `identity_id`, `permission`, and `scope` (`node` lineage walk or `app_wide`). Scoped API keys must carry the evaluate scope (`403` otherwise). Rate-limited to 500 requests/minute.
+         * @description Evaluates up to 100 permission checks in a single request (more is refused with `400`), returning a `{ items }` array of decisions in the same order as the input `checks`, each with the same shape as the single evaluate endpoint. Every check is resolved independently against its own `identity_id`, `permission`, and `scope` (`node` lineage walk or `app_wide`). Scoped API keys must carry the evaluate scope (`403` otherwise). Rate-limited to 500 requests/minute.
          */
         post: operations["ApiPermissionsController_evaluateBulk"];
         delete?: never;
@@ -588,7 +588,7 @@ interface paths {
         };
         /**
          * List an identity's active sessions (admin)
-         * @description Lists an identity's active sessions in the caller's Environment (server-to-server admin): the rows a customer reads to confirm from its own side that a sign-out took, or to show a person where they are signed in. Each row is a session's current refresh token, so `id` changes on every refresh. Sessions the identity holds in its other Environments are not listed. Returns `404` when the identity has no membership in this Environment.
+         * @description Lists one page of an identity's active sessions in the caller's Environment (server-to-server admin), newest first, taking `page` and `take` only: the rows a customer reads to confirm from its own side that a sign-out took, or to show a person where they are signed in. Each row is a session's current refresh token, so `id` changes on every refresh. Sessions the identity holds in its other Environments are not listed. Returns `404` when the identity has no membership in this Environment.
          */
         get: operations["ApiIdentitiesController_listIdentitySessions"];
         put?: never;
@@ -768,7 +768,7 @@ interface paths {
         };
         /**
          * 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.
+         * @description Returns, for the current Environment, one page of `(permission, node_id)` rows: every permission the identity holds, paired with each hierarchy node its grants were made at — the nodes themselves, **not** expanded through their descendants. Rows are ordered by permission, then node; a caller building the whole map walks every page. 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 parent edges fetched once from `GET /api/v1/nodes/parents` 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;
@@ -891,8 +891,8 @@ interface paths {
             cookie?: never;
         };
         /**
-         * List hierarchy (scoped tree)
-         * @description Returns the caller's accessible hierarchy as a nested tree for the current Environment, each node annotated with `access_state`, `can_access`, and `can_manage`. `user` principals (dashboard), which need the Console capability covering `hierarchy.view`, see the full tree; API-key principals see only the subtree their `access_mode`/scopes grant — `full_access` unlocks everything, while scoped keys see nodes reachable via `hierarchy.view`. The response also includes a `scope` block listing `accessible_node_ids`, `scope_root_node_ids`, and `entry_node_ids`.
+         * List hierarchy nodes (scoped, paged)
+         * @description Returns one page of the caller's hierarchy for the current Environment as a flat list, each node carrying its `parent_node_id` and annotated with `access_state`, `can_access`, `can_manage` and its identity counts. A caller rebuilding the tree walks every page and links each node to its parent; a node whose parent is not in the listing is a top of the caller's scope. `user` principals (dashboard), which need the Console capability covering `hierarchy.view`, see every node; API-key principals see only what their `access_mode`/scopes grant — `full_access` unlocks everything, while scoped keys see nodes reachable via `hierarchy.view`. `context_only` nodes are the ancestors shown as the path to the caller's scope. Searches names and slugs with `q`; sorts by `name` or `created` (default, oldest first).
          */
         get: operations["ApiNodesController_listNodes"];
         put?: never;
@@ -916,7 +916,7 @@ interface paths {
         };
         /**
          * 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.
+         * @description Returns the same hierarchy `GET /api/v1/nodes` describes, scoped identically, but as `{ id, parent_node_id }` pairs and nothing else, one page at a time, ordered by node id. Intended for a client that evaluates authorization locally: it walks every page into a child-to-parent map and reads none of the nodes' names, statuses, access flags or counts. At fifty thousand nodes the full listing 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 node listing's and from every other page's: a tag from one representation or page never satisfies a request for another. A `304` on the first page means the whole hierarchy is unchanged.
          */
         get: operations["ApiNodesController_listNodeParents"];
         put?: never;
@@ -964,7 +964,7 @@ interface paths {
         };
         /**
          * Get subtree from a node
-         * @description Returns the subtree rooted at the given node as a nested structure, drawn from the caller's accessible hierarchy in the current Environment. The node must be within the caller's accessible scope (otherwise `403`); a node id that resolves but is absent from the scoped tree returns `404`. Each node carries the same access annotations as the full tree listing.
+         * @description Returns one page of the given node and its descendants within the caller's scope in the current Environment, flat, each node carrying its `parent_node_id` and the same access annotations and counts as `GET /api/v1/nodes`. The node must be within the caller's accessible scope (otherwise `403`). Searches names and slugs with `q`; sorts by `name` or `created` (default, oldest first).
          */
         get: operations["ApiNodesController_getSubtree"];
         put?: never;
@@ -1004,7 +1004,7 @@ interface paths {
         };
         /**
          * Get direct children of a node
-         * @description Returns the direct children of a node as an `items` array (one level only, not the full subtree), scoped to the current Environment. The node must be within the caller's accessible scope, otherwise `403` is returned.
+         * @description Returns one page of a node's direct children (one level only, not the full subtree) in the current Environment. The node must be within the caller's accessible scope, otherwise `403` is returned. Searches names and slugs with `q`; sorts by `name` or `created` (default, oldest first).
          */
         get: operations["ApiNodesController_getChildren"];
         put?: never;
@@ -1338,7 +1338,7 @@ interface paths {
         put?: never;
         /**
          * Add a member to an organization
-         * @description Adds a member: assigns `role_id` to `identity_id` at the organization. The identity must already hold an active membership in this Environment (invite by email instead for someone who does not). A member holds exactly one role per organization, so an identity that is already a member returns `409` — use the change-role operation. Requires the `rbac.manage_assignments` permission at the organization and emits `organization.member.added`.
+         * @description Adds a member: assigns `role_id` to `identity_id` at the organization. The identity must already hold an active membership in this Environment (invite by email instead for someone who does not). A member holds exactly one role per organization, so an identity that is already a member returns `409` — use the change-role operation. Requires the `rbac.manage_assignments` permission at the organization and emits `organization.member.added`. An organization's own administrator, signed in with an identity token and admitted by `canopy:organization.manage` alone, is refused with `403` (`organization.member_add_requires_invite`): the person never agreed to join, so the administrator invites them instead.
          */
         post: operations["ApiOrganizationsController_addMember"];
         delete?: never;
@@ -1382,7 +1382,7 @@ interface paths {
         put?: never;
         /**
          * Reset a member's multi-factor authentication
-         * @description The organization's own administrator, or the developer, clears a member's multi-factor enrolment: every factor, the recovery codes and the trusted devices, so the person enrols afresh at their next sign-in. For a member who lost their authenticator. Sessions already open are left alone. Audited as `identity.mfa.admin.forced_reset`. Returns `404` when the identity is not a member. Responds `204 No Content`; requires `hierarchy.manage` or `canopy:organization.manage` at the organization.
+         * @description The organization's own administrator, or the developer, clears a member's multi-factor enrolment: every factor and the recovery codes, held once per identity, and the devices trusted in this Environment, so the person enrols afresh at their next sign-in. For a member who lost their authenticator. Sessions already open are left alone. Audited as `identity.mfa.admin.forced_reset`. Returns `404` when the identity is not a member. Responds `204 No Content`; requires `hierarchy.manage` or `canopy:organization.manage` at the organization.
          */
         post: operations["ApiOrganizationsController_resetMemberMfa"];
         delete?: never;
@@ -1752,7 +1752,7 @@ interface paths {
         };
         /**
          * List the groups an organization's provider has pushed
-         * @description Pushed groups returned, each with its role mapping and member count
+         * @description One page of pushed groups, each with its role mapping and member count, by display name unless sorted (`sort_by` `name` or `created`); `q` searches display names and external ids
          */
         get: operations["ApiOrganizationDirectoryGroupsController_list"];
         put?: never;
@@ -2270,7 +2270,7 @@ interface paths {
         put?: never;
         /**
          * Register a new OAuth client
-         * @description Registers a new confidential OAuth client in the current Environment with the given `name`, `redirect_uris`, and optional `scopes` (defaulting to `openid profile email`). Generates the `client_id` and a `client_secret` that is bcrypt-hashed at rest; the raw secret is returned in this response only and is never retrievable again. Responds `201 Created`.
+         * @description Registers a new confidential OAuth client in the current Environment with the given `name`, `redirect_uris`, and optional `scopes` (defaulting to `openid profile email`), each one of `openid`, `profile`, `email`, `org` and `permissions`; any other value is refused with `400` (`oauth.client_scope_unknown`). Generates the `client_id` and a `client_secret` that is bcrypt-hashed at rest; the raw secret is returned in this response only and is never retrievable again. Responds `201 Created`.
          */
         post: operations["ApiOAuthClientsController_create"];
         delete?: never;
@@ -2322,7 +2322,7 @@ interface paths {
         head?: never;
         /**
          * Update OAuth client
-         * @description Updates an OAuth client's mutable fields (`name`, `redirect_uris`, `post_logout_redirect_uris`, `backchannel_logout_uri`, `scopes`, `is_active`, `invite_redirect_url`, `initiate_login_uri`), scoped to the current Environment. Returns the updated client, or `404` when the client is not found in this Environment. The secret is not rotated here.
+         * @description Updates an OAuth client's mutable fields (`name`, `redirect_uris`, `post_logout_redirect_uris`, `backchannel_logout_uri`, `scopes`, `is_active`, `invite_redirect_url`, `initiate_login_uri`), scoped to the current Environment. A `scopes` value outside `openid`, `profile`, `email`, `org` and `permissions` is refused with `400` (`oauth.client_scope_unknown`). Returns the updated client, or `404` when the client is not found in this Environment. The secret is not rotated here.
          */
         patch: operations["ApiOAuthClientsController_update"];
         trace?: never;
@@ -2383,14 +2383,14 @@ interface paths {
         post?: never;
         /**
          * Delete an API key
-         * @description Permanently deletes an API key from the active Environment. The row is removed entirely rather than just disabled, so the key can never authenticate again and disappears from listings; the lifecycle remains traceable in the audit log. Returns `204 No Content` on success and `404` when no key with the given id exists in the active Environment.
+         * @description Permanently deletes an API key from the active Environment. The row is removed entirely rather than just disabled, so the key can never authenticate again and disappears from listings; the lifecycle remains traceable in the audit log. Returns `204 No Content` on success and `404` when no key with the given id exists in the active Environment. A scoped API key can act only on scoped keys whose scopes it holds itself; any other key is refused with `403`.
          */
         delete: operations["ApiApiKeysController_delete"];
         options?: never;
         head?: never;
         /**
          * Activate or deactivate an API key
-         * @description Enables or disables an existing API key in the current Environment via the `is_active` flag. Disabling is reversible: a disabled key is rejected by authentication immediately and can be re-enabled later. Returns the key's metadata with no secret. Returns `404` when no key with the given id exists in the active Environment.
+         * @description Enables or disables an existing API key in the current Environment via the `is_active` flag. Disabling is reversible: a disabled key is rejected by authentication immediately and can be re-enabled later. Returns the key's metadata with no secret. Returns `404` when no key with the given id exists in the active Environment. A scoped API key can act only on scoped keys whose scopes it holds itself; any other key is refused with `403`.
          */
         patch: operations["ApiApiKeysController_update"];
         trace?: never;
@@ -2406,7 +2406,7 @@ interface paths {
         put?: never;
         /**
          * Rotate an API key's secret
-         * @description Rotates the secret of an existing API key in place, minting a brand-new `cnpy_`-prefixed value for the same row while preserving its id, name, `scopes`, `access_mode`, expiry, and audit lineage. The previous secret is invalidated immediately and the new plaintext is returned exactly once in the `key` field. `is_active` is left untouched — rotating does not re-enable a disabled key. Returns `404` when no key with the given id exists in the active Environment.
+         * @description Rotates the secret of an existing API key in place, minting a brand-new `cnpy_`-prefixed value for the same row while preserving its id, name, `scopes`, `access_mode`, expiry, and audit lineage. The previous secret is invalidated immediately and the new plaintext is returned exactly once in the `key` field. `is_active` is left untouched — rotating does not re-enable a disabled key. Returns `404` when no key with the given id exists in the active Environment. A scoped API key can act only on scoped keys whose scopes it holds itself; any other key is refused with `403`.
          */
         post: operations["ApiApiKeysController_rotateSecret"];
         delete?: never;
@@ -2476,11 +2476,11 @@ interface components {
             allowed: boolean;
             permission: string;
             /**
-             * @description Echo of the `scope` the caller asked for. `app_wide` answers are 'matched somewhere in the tree' — never treat them as scoped to a specific node.
+             * @description Echo of the `scope` the caller asked for. `app_wide` answers are 'matched somewhere in the Environment' — never treat them as scoped to a specific node.
              * @enum {string}
              */
             scope_evaluated: "node" | "app_wide";
-            /** @description The hierarchy node the decision was anchored to. Always set for `scope_evaluated: "node"`; always null for `scope_evaluated: "app_wide"` because the answer is org-scoped, not node-scoped. */
+            /** @description The hierarchy node the decision was anchored to. Always set for `scope_evaluated: "node"`; always null for `scope_evaluated: "app_wide"` because the answer covers the whole Environment, not one node. */
             effective_node_id?: string | null;
             /** @description Ids of the roles whose assignments produced a node-scoped allow. Always empty for `scope_evaluated: "app_wide"`, whose answer is not tied to a node, and for a deny. */
             granting_roles: string[];
@@ -2491,7 +2491,7 @@ interface components {
             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.
+             * @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 Environment?' question — useful for UI gating, **never** for resource-scoped enforcement. `node` requires `node_id`; `app_wide` forbids it.
              * @enum {string}
              */
             scope: "node" | "app_wide";
@@ -2503,7 +2503,7 @@ interface components {
             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.
+             * @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 Environment?' question — useful for UI gating, **never** for resource-scoped enforcement. `node` requires `node_id`; `app_wide` forbids it.
              * @enum {string}
              */
             scope: "node" | "app_wide";
@@ -2511,6 +2511,7 @@ interface components {
             node_id?: string;
         };
         BulkEvaluatePermissionDto: {
+            /** @description Between 1 and 100 checks. More is refused with a 400. */
             checks: components["schemas"]["EvaluateCheckDto"][];
         };
         PermissionTraceAssignmentDto: {
@@ -2741,8 +2742,11 @@ interface components {
         IdentityGrantResponseDto: {
             /** @example reports.view */
             permission: string;
-            /** @description Hierarchy node ids the permission was granted at. Not expanded through descendants. */
-            nodes: string[];
+            /**
+             * Format: uuid
+             * @description The hierarchy node the permission was granted at. Not expanded through descendants.
+             */
+            node_id: string;
         };
         IdentityInviteResponseDto: {
             id: string;
@@ -2862,7 +2866,7 @@ interface components {
             /** @description Arbitrary metadata */
             metadata?: Record<string, unknown>;
         };
-        HierarchyTreeNodeDto: {
+        ScopedNodeResponseDto: {
             id: string;
             name: string;
             /** @description Optional free-text description shown under the node name. */
@@ -2876,7 +2880,6 @@ interface components {
             access_state: "accessible" | "context_only";
             can_access: boolean;
             can_manage: boolean;
-            children: components["schemas"]["HierarchyTreeNodeDto"][];
             /** @description Optimistic-lock version. Send back as the `If-Match` header when mutating this node to detect concurrent edits. */
             version: number;
             /** @description Distinct active identities directly assigned at this node (excludes inherited). */
@@ -2884,15 +2887,6 @@ interface components {
             /** @description Distinct active identities inherited from this node's ancestors. */
             inherited_count: number;
         };
-        HierarchyScopeDto: {
-            accessible_node_ids: string[];
-            scope_root_node_ids: string[];
-            entry_node_ids: string[];
-        };
-        ScopedHierarchyTreeResponseDto: {
-            tree: components["schemas"]["HierarchyTreeNodeDto"][];
-            scope: components["schemas"]["HierarchyScopeDto"];
-        };
         NodeParentEdgeResponseDto: {
             id: string;
             /** @description Null for the root node, which has no parent. */
@@ -6276,12 +6270,14 @@ interface operations {
                 page?: number;
                 /** @description Items per page (1-100, default 20) */
                 take?: number;
-                /** @description Search term */
+                /** @description Search names and emails */
                 q?: string;
-                /** @description Column to sort by. Allowed values depend on the endpoint. */
-                sort_by?: string;
+                /** @description Sort column. Defaults to `name`, A to Z. */
+                sort_by?: "name" | "email" | "created";
                 /** @description Sort direction */
                 order?: "asc" | "desc";
+                /** @description Filter by active/inactive status. Omit to show all. */
+                status?: "active" | "inactive";
             };
             header?: never;
             path?: never;
@@ -6504,16 +6500,16 @@ interface operations {
                 page?: number;
                 /** @description Items per page (1-100, default 20) */
                 take?: number;
-                /** @description Search term */
+                /** @description Search names and emails */
                 q?: string;
-                /** @description Column to sort by. Allowed values depend on the endpoint. */
-                sort_by?: string;
+                /** @description Sort column. Defaults to `name`, A to Z. */
+                sort_by?: "name" | "email" | "created";
                 /** @description Sort direction */
                 order?: "asc" | "desc";
-                /** @description Filter by role ID (UUID) or "no_assignment" for unassigned identities */
-                role_id?: string;
                 /** @description Filter by active/inactive status. Omit to show all. */
                 status?: "active" | "inactive";
+                /** @description Filter by role ID (UUID) or "no_assignment" for unassigned identities */
+                role_id?: string;
             };
             header?: never;
             path?: never;
@@ -7495,7 +7491,12 @@ interface operations {
     };
     ApiIdentitiesController_listIdentitySessions: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Page number (1-based) */
+                page?: number;
+                /** @description Items per page (1-100, default 20) */
+                take?: number;
+            };
             header?: never;
             path: {
                 id: string;
@@ -7504,7 +7505,7 @@ interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Every session the identity holds that is neither revoked nor expired, newest first: the session's current refresh token id (what the per-session revoke takes), when it was signed in and when it expires, the browser's address and user agent, and the organization it is acting in. */
+            /** @description One page of the sessions the identity holds that are neither revoked nor expired, newest first: the session's current refresh token id (what the per-session revoke takes), when it was signed in and when it expires, the browser's address and user agent, and the organization it is acting in. */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -7512,6 +7513,7 @@ interface operations {
                 content: {
                     "application/json": {
                         items: components["schemas"]["IdentitySessionResponseDto"][];
+                        pagination: components["schemas"]["PageMetaDto"];
                     };
                 };
             };
@@ -8241,10 +8243,10 @@ interface operations {
                 page?: number;
                 /** @description Items per page (1-100, default 20) */
                 take?: number;
-                /** @description Search term */
+                /** @description Search role and node names */
                 q?: string;
-                /** @description Column to sort by. Allowed values depend on the endpoint. */
-                sort_by?: string;
+                /** @description Sort column. Defaults to `created`, oldest first. */
+                sort_by?: "role" | "node" | "created";
                 /** @description Sort direction */
                 order?: "asc" | "desc";
             };
@@ -8464,7 +8466,12 @@ interface operations {
     };
     ApiIdentitiesController_getIdentityGrants: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Page number (1-based) */
+                page?: number;
+                /** @description Items per page (1-100, default 20) */
+                take?: number;
+            };
             header?: never;
             path: {
                 id: string;
@@ -8473,7 +8480,7 @@ interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Grant map returned */
+            /** @description One page of grant roots, one row per permission and node, ordered by permission then node */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -8481,6 +8488,7 @@ interface operations {
                 content: {
                     "application/json": {
                         items: components["schemas"]["IdentityGrantResponseDto"][];
+                        pagination: components["schemas"]["PageMetaDto"];
                     };
                 };
             };
@@ -9244,9 +9252,20 @@ interface operations {
     };
     ApiNodesController_listNodes: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Page number (1-based) */
+                page?: number;
+                /** @description Items per page (1-100, default 20) */
+                take?: number;
+                /** @description Search node names and slugs */
+                q?: string;
+                /** @description Sort column. Defaults to `created`, oldest first. */
+                sort_by?: "name" | "created";
+                /** @description Sort direction */
+                order?: "asc" | "desc";
+            };
             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. */
+                /** @description An `ETag` from a previous response for the same page and query. Answers `304 Not Modified` when the hierarchy has not changed since, so a client holding a cached copy can revalidate on a short interval without re-reading it. */
                 "If-None-Match"?: string;
             };
             path?: never;
@@ -9254,25 +9273,26 @@ interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Scoped hierarchy tree returned */
+            /** @description One page of the caller's scoped nodes */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
                     "application/json": {
-                        data: components["schemas"]["ScopedHierarchyTreeResponseDto"];
+                        items: components["schemas"]["ScopedNodeResponseDto"][];
+                        pagination: components["schemas"]["PageMetaDto"];
                     };
                 };
             };
-            /** @description The hierarchy is unchanged since the supplied `ETag`. No body; keep using the cached tree. */
+            /** @description The hierarchy is unchanged since the supplied `ETag`. No body; keep using the cached copy. */
             304: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content?: never;
             };
-            /** @description The request sent both an `X-API-Key` and an `Authorization` header; send one */
+            /** @description The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range; or the request sent both an `X-API-Key` and an `Authorization` header */
             400: {
                 headers: {
                     [name: string]: unknown;
@@ -9283,7 +9303,7 @@ interface operations {
                      *       "error": {
                      *         "statusCode": 400,
                      *         "code": null,
-                     *         "message": "The request sent both an `X-API-Key` and an `Authorization` header; send one",
+                     *         "message": "The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range; or the request sent both an `X-API-Key` and an `Authorization` header",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
                      *         "path": "/api/v1/nodes",
                      *         "method": "GET"
@@ -9449,9 +9469,14 @@ interface operations {
     };
     ApiNodesController_listNodeParents: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Page number (1-based) */
+                page?: number;
+                /** @description Items per page (1-100, default 20) */
+                take?: number;
+            };
             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. */
+                /** @description An `ETag` from a previous response for the same page and query. Answers `304 Not Modified` when the hierarchy has not changed since, so a client holding a cached copy can revalidate on a short interval without re-reading it. */
                 "If-None-Match"?: string;
             };
             path?: never;
@@ -9459,7 +9484,7 @@ interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Parent edges returned */
+            /** @description One page of parent edges, by node id */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -9467,17 +9492,18 @@ interface operations {
                 content: {
                     "application/json": {
                         items: components["schemas"]["NodeParentEdgeResponseDto"][];
+                        pagination: components["schemas"]["PageMetaDto"];
                     };
                 };
             };
-            /** @description The hierarchy is unchanged since the supplied `ETag`. No body; keep using the cached tree. */
+            /** @description The hierarchy is unchanged since the supplied `ETag`. No body; keep using the cached copy. */
             304: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content?: never;
             };
-            /** @description The request sent both an `X-API-Key` and an `Authorization` header; send one */
+            /** @description The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range; or the request sent both an `X-API-Key` and an `Authorization` header */
             400: {
                 headers: {
                     [name: string]: unknown;
@@ -9488,7 +9514,7 @@ interface operations {
                      *       "error": {
                      *         "statusCode": 400,
                      *         "code": null,
-                     *         "message": "The request sent both an `X-API-Key` and an `Authorization` header; send one",
+                     *         "message": "The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range; or the request sent both an `X-API-Key` and an `Authorization` header",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
                      *         "path": "/api/v1/nodes/parents",
                      *         "method": "GET"
@@ -9577,7 +9603,7 @@ interface operations {
                      *         "code": null,
                      *         "message": "The request sent both an `X-API-Key` and an `Authorization` header; send one",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
-                     *         "path": "/api/v1/nodes",
+                     *         "path": "/api/v1/nodes/{id}",
                      *         "method": "GET"
                      *       }
                      *     }
@@ -9918,7 +9944,18 @@ interface operations {
     };
     ApiNodesController_getSubtree: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Page number (1-based) */
+                page?: number;
+                /** @description Items per page (1-100, default 20) */
+                take?: number;
+                /** @description Search node names and slugs */
+                q?: string;
+                /** @description Sort column. Defaults to `created`, oldest first. */
+                sort_by?: "name" | "created";
+                /** @description Sort direction */
+                order?: "asc" | "desc";
+            };
             header?: never;
             path: {
                 id: string;
@@ -9927,18 +9964,19 @@ interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Subtree returned */
+            /** @description One page of the node and its descendants in scope */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
                     "application/json": {
-                        data: components["schemas"]["HierarchyTreeNodeDto"];
+                        items: components["schemas"]["ScopedNodeResponseDto"][];
+                        pagination: components["schemas"]["PageMetaDto"];
                     };
                 };
             };
-            /** @description The request sent both an `X-API-Key` and an `Authorization` header; send one */
+            /** @description The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range; or the request sent both an `X-API-Key` and an `Authorization` header */
             400: {
                 headers: {
                     [name: string]: unknown;
@@ -9949,9 +9987,9 @@ interface operations {
                      *       "error": {
                      *         "statusCode": 400,
                      *         "code": null,
-                     *         "message": "The request sent both an `X-API-Key` and an `Authorization` header; send one",
+                     *         "message": "The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range; or the request sent both an `X-API-Key` and an `Authorization` header",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
-                     *         "path": "/api/v1/nodes",
+                     *         "path": "/api/v1/nodes/{id}/tree",
                      *         "method": "GET"
                      *       }
                      *     }
@@ -10038,7 +10076,7 @@ interface operations {
                      *         "code": null,
                      *         "message": "The request sent both an `X-API-Key` and an `Authorization` header; send one",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
-                     *         "path": "/api/v1/nodes",
+                     *         "path": "/api/v1/nodes/{id}",
                      *         "method": "GET"
                      *       }
                      *     }
@@ -10092,7 +10130,18 @@ interface operations {
     };
     ApiNodesController_getChildren: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Page number (1-based) */
+                page?: number;
+                /** @description Items per page (1-100, default 20) */
+                take?: number;
+                /** @description Search node names and slugs */
+                q?: string;
+                /** @description Sort column. Defaults to `created`, oldest first. */
+                sort_by?: "name" | "created";
+                /** @description Sort direction */
+                order?: "asc" | "desc";
+            };
             header?: never;
             path: {
                 id: string;
@@ -10101,7 +10150,7 @@ interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Children returned */
+            /** @description One page of the node's children */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -10109,10 +10158,11 @@ interface operations {
                 content: {
                     "application/json": {
                         items: components["schemas"]["NodeResponseDto"][];
+                        pagination: components["schemas"]["PageMetaDto"];
                     };
                 };
             };
-            /** @description The request sent both an `X-API-Key` and an `Authorization` header; send one */
+            /** @description The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range; or the request sent both an `X-API-Key` and an `Authorization` header */
             400: {
                 headers: {
                     [name: string]: unknown;
@@ -10123,9 +10173,9 @@ interface operations {
                      *       "error": {
                      *         "statusCode": 400,
                      *         "code": null,
-                     *         "message": "The request sent both an `X-API-Key` and an `Authorization` header; send one",
+                     *         "message": "The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range; or the request sent both an `X-API-Key` and an `Authorization` header",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
-                     *         "path": "/api/v1/nodes",
+                     *         "path": "/api/v1/nodes/{id}/children",
                      *         "method": "GET"
                      *       }
                      *     }
@@ -10557,10 +10607,10 @@ interface operations {
                 page?: number;
                 /** @description Items per page (1-100, default 20) */
                 take?: number;
-                /** @description Search term */
+                /** @description Search organization names and slugs */
                 q?: string;
-                /** @description Column to sort by. Allowed values depend on the endpoint. */
-                sort_by?: string;
+                /** @description Sort column. Defaults to `name`, A to Z. */
+                sort_by?: "name" | "created";
                 /** @description Sort direction */
                 order?: "asc" | "desc";
                 /** @description Exact match on the organization's `external_id` (your own id for it). Answers one organization or none. */
@@ -12634,10 +12684,10 @@ interface operations {
                 page?: number;
                 /** @description Items per page (1-100, default 20) */
                 take?: number;
-                /** @description Search term */
+                /** @description Search member names and emails */
                 q?: string;
-                /** @description Column to sort by. Allowed values depend on the endpoint. */
-                sort_by?: string;
+                /** @description Sort column. Defaults to `created`, oldest membership first. */
+                sort_by?: "name" | "email" | "role" | "created";
                 /** @description Sort direction */
                 order?: "asc" | "desc";
                 /** @description Only members holding this role */
@@ -12819,7 +12869,7 @@ interface operations {
                     "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) */
+            /** @description The caller is an organization administrator signed in as an identity and holds no `rbac.manage_assignments` at the organization; an organization administrator adds people by invitation (`organization.member_add_requires_invite`). Also a caller without the permissions the route needs */
             403: {
                 headers: {
                     [name: string]: unknown;
@@ -12830,10 +12880,10 @@ interface operations {
                      *       "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)",
+                     *         "message": "The caller is an organization administrator signed in as an identity and holds no `rbac.manage_assignments` at the organization; an organization administrator adds people by invitation (`organization.member_add_requires_invite`). Also a caller without the permissions the route needs",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
-                     *         "path": "/api/v1/organizations",
-                     *         "method": "GET"
+                     *         "path": "/api/v1/organizations/{id}/members",
+                     *         "method": "POST"
                      *       }
                      *     }
                      */
@@ -13156,7 +13206,7 @@ interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Factors, recovery codes and trusted devices cleared; the member enrols again at their next sign-in */
+            /** @description Factors and recovery codes cleared, and the devices trusted in this Environment; the member enrols again at their next sign-in */
             204: {
                 headers: {
                     [name: string]: unknown;
@@ -13247,7 +13297,7 @@ interface operations {
                     "application/json": components["schemas"]["ErrorResponseDto"];
                 };
             };
-            /** @description The caller is an organization administrator and the member also belongs to another organization in the Environment; the second factor is held once per identity, so only the application's administrators may reset it (`organization.member_mfa_shared`) */
+            /** @description The caller is an organization administrator and the member also belongs to another organization, or holds an active membership in another Environment of the Account; the second factor is held once per identity, so only the application's administrators may reset it (`organization.member_mfa_shared`) */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -13258,7 +13308,7 @@ interface operations {
                      *       "error": {
                      *         "statusCode": 409,
                      *         "code": null,
-                     *         "message": "The caller is an organization administrator and the member also belongs to another organization in the Environment; the second factor is held once per identity, so only the application's administrators may reset it (`organization.member_mfa_shared`)",
+                     *         "message": "The caller is an organization administrator and the member also belongs to another organization, or holds an active membership in another Environment of the Account; the second factor is held once per identity, so only the application's administrators may reset it (`organization.member_mfa_shared`)",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
                      *         "path": "/api/v1/organizations/{id}/members/{identityId}/mfa/reset",
                      *         "method": "POST"
@@ -13279,11 +13329,11 @@ interface operations {
                 take?: number;
                 /** @description Search term */
                 q?: string;
-                /** @description Column to sort by. Allowed values depend on the endpoint. */
-                sort_by?: string;
+                /** @description Column to sort by. Defaults to `created`, newest first. */
+                sort_by?: "name" | "email" | "created";
                 /** @description Sort direction */
                 order?: "asc" | "desc";
-                /** @description Filter by invitation status */
+                /** @description Filter by invite status */
                 status?: "pending" | "accepted" | "revoked" | "expired";
             };
             header?: never;
@@ -16145,7 +16195,18 @@ interface operations {
     };
     ApiOrganizationDirectoryGroupsController_list: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Page number (1-based) */
+                page?: number;
+                /** @description Items per page (1-100, default 20) */
+                take?: number;
+                /** @description Search group display names and external ids */
+                q?: string;
+                /** @description Sort column. Defaults to `name`, A to Z. */
+                sort_by?: "name" | "created";
+                /** @description Sort direction */
+                order?: "asc" | "desc";
+            };
             header?: never;
             path: {
                 id: string;
@@ -16154,7 +16215,7 @@ interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Pushed groups returned, each with its role mapping and member count */
+            /** @description One page of pushed groups, each with its role mapping and member count, by display name unless sorted (`sort_by` `name` or `created`); `q` searches display names and external ids */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -16162,6 +16223,7 @@ interface operations {
                 content: {
                     "application/json": {
                         items: components["schemas"]["ScimGroupResponseDto"][];
+                        pagination: components["schemas"]["PageMetaDto"];
                     };
                 };
             };
@@ -19307,10 +19369,10 @@ interface operations {
                 page?: number;
                 /** @description Items per page (1-100, default 20) */
                 take?: number;
-                /** @description Search term */
+                /** @description Search the endpoint URL */
                 q?: string;
-                /** @description Column to sort by. Allowed values depend on the endpoint. */
-                sort_by?: string;
+                /** @description Sort column. Defaults to `created`, newest first. */
+                sort_by?: "url" | "created";
                 /** @description Sort direction */
                 order?: "asc" | "desc";
             };
@@ -19578,10 +19640,10 @@ interface operations {
                 page?: number;
                 /** @description Items per page (1-100, default 20) */
                 take?: number;
-                /** @description Search term */
+                /** @description Search the event type */
                 q?: string;
-                /** @description Column to sort by. Allowed values depend on the endpoint. */
-                sort_by?: string;
+                /** @description Sort column. Defaults to `created`, newest first. */
+                sort_by?: "created" | "event_type" | "status";
                 /** @description Sort direction */
                 order?: "asc" | "desc";
             };
@@ -20022,10 +20084,10 @@ interface operations {
                 page?: number;
                 /** @description Items per page (1-100, default 20) */
                 take?: number;
-                /** @description Search term */
+                /** @description Search client names */
                 q?: string;
-                /** @description Column to sort by. Allowed values depend on the endpoint. */
-                sort_by?: string;
+                /** @description Sort column. Defaults to `created`, newest first. */
+                sort_by?: "name" | "created";
                 /** @description Sort direction */
                 order?: "asc" | "desc";
             };
@@ -20136,7 +20198,7 @@ interface operations {
                     };
                 };
             };
-            /** @description The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range, `backchannel_logout_uri` names an address Canopy's servers will not call, or `initiate_login_uri` is malformed or not `https` (loopback hosts excepted); or the request sent both an `X-API-Key` and an `Authorization` header */
+            /** @description The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range, `backchannel_logout_uri` names an address Canopy's servers will not call, `initiate_login_uri` is malformed or not `https` (loopback hosts excepted), or `scopes` names a scope Canopy does not issue (`oauth.client_scope_unknown`); or the request sent both an `X-API-Key` and an `Authorization` header */
             400: {
                 headers: {
                     [name: string]: unknown;
@@ -20147,7 +20209,7 @@ interface operations {
                      *       "error": {
                      *         "statusCode": 400,
                      *         "code": null,
-                     *         "message": "The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range, `backchannel_logout_uri` names an address Canopy's servers will not call, or `initiate_login_uri` is malformed or not `https` (loopback hosts excepted); or the request sent both an `X-API-Key` and an `Authorization` header",
+                     *         "message": "The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range, `backchannel_logout_uri` names an address Canopy's servers will not call, `initiate_login_uri` is malformed or not `https` (loopback hosts excepted), or `scopes` names a scope Canopy does not issue (`oauth.client_scope_unknown`); or the request sent both an `X-API-Key` and an `Authorization` header",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
                      *         "path": "/api/v1/oauth-clients",
                      *         "method": "POST"
@@ -20547,7 +20609,7 @@ interface operations {
                     };
                 };
             };
-            /** @description The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range, `backchannel_logout_uri` names an address Canopy's servers will not call, or `initiate_login_uri` is malformed or not `https` (loopback hosts excepted); or the request sent both an `X-API-Key` and an `Authorization` header */
+            /** @description The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range, `backchannel_logout_uri` names an address Canopy's servers will not call, `initiate_login_uri` is malformed or not `https` (loopback hosts excepted), or `scopes` names a scope Canopy does not issue (`oauth.client_scope_unknown`); or the request sent both an `X-API-Key` and an `Authorization` header */
             400: {
                 headers: {
                     [name: string]: unknown;
@@ -20558,7 +20620,7 @@ interface operations {
                      *       "error": {
                      *         "statusCode": 400,
                      *         "code": null,
-                     *         "message": "The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range, `backchannel_logout_uri` names an address Canopy's servers will not call, or `initiate_login_uri` is malformed or not `https` (loopback hosts excepted); or the request sent both an `X-API-Key` and an `Authorization` header",
+                     *         "message": "The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range, `backchannel_logout_uri` names an address Canopy's servers will not call, `initiate_login_uri` is malformed or not `https` (loopback hosts excepted), or `scopes` names a scope Canopy does not issue (`oauth.client_scope_unknown`); or the request sent both an `X-API-Key` and an `Authorization` header",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
                      *         "path": "/api/v1/oauth-clients/{id}",
                      *         "method": "PATCH"
@@ -20748,10 +20810,10 @@ interface operations {
                 page?: number;
                 /** @description Items per page (1-100, default 20) */
                 take?: number;
-                /** @description Search term */
+                /** @description Search key names */
                 q?: string;
-                /** @description Column to sort by. Allowed values depend on the endpoint. */
-                sort_by?: string;
+                /** @description Sort column. Defaults to `created`, newest first. */
+                sort_by?: "name" | "created";
                 /** @description Sort direction */
                 order?: "asc" | "desc";
             };
@@ -21050,7 +21112,7 @@ interface operations {
                     "application/json": components["schemas"]["ErrorResponseDto"];
                 };
             };
-            /** @description The bearer token is not an admin or platform token, or the caller lacks the permission this operation checks: a scoped API key without that scope, an admin without the Account capability that covers it, or, for a node-scoped check, a node outside this Environment */
+            /** @description The caller lacks `api_key.manage` (a scoped API key without that scope, or an admin without the Account capability that covers it), or is a scoped API key acting on a key with more access than its own: a `full_access` key, or one holding a scope outside its own (`api_key.access_exceeds_caller`) */
             403: {
                 headers: {
                     [name: string]: unknown;
@@ -21061,10 +21123,10 @@ interface operations {
                      *       "error": {
                      *         "statusCode": 403,
                      *         "code": null,
-                     *         "message": "The bearer token is not an admin or platform token, or the caller lacks the permission this operation checks: a scoped API key without that scope, an admin without the Account capability that covers it, or, for a node-scoped check, a node outside this Environment",
+                     *         "message": "The caller lacks `api_key.manage` (a scoped API key without that scope, or an admin without the Account capability that covers it), or is a scoped API key acting on a key with more access than its own: a `full_access` key, or one holding a scope outside its own (`api_key.access_exceeds_caller`)",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
-                     *         "path": "/api/v1/api-keys",
-                     *         "method": "GET"
+                     *         "path": "/api/v1/api-keys/{id}",
+                     *         "method": "DELETE"
                      *       }
                      *     }
                      */
@@ -21162,7 +21224,7 @@ interface operations {
                     "application/json": components["schemas"]["ErrorResponseDto"];
                 };
             };
-            /** @description The bearer token is not an admin or platform token, or the caller lacks the permission this operation checks: a scoped API key without that scope, an admin without the Account capability that covers it, or, for a node-scoped check, a node outside this Environment */
+            /** @description The caller lacks `api_key.manage` (a scoped API key without that scope, or an admin without the Account capability that covers it), or is a scoped API key acting on a key with more access than its own: a `full_access` key, or one holding a scope outside its own (`api_key.access_exceeds_caller`) */
             403: {
                 headers: {
                     [name: string]: unknown;
@@ -21173,10 +21235,10 @@ interface operations {
                      *       "error": {
                      *         "statusCode": 403,
                      *         "code": null,
-                     *         "message": "The bearer token is not an admin or platform token, or the caller lacks the permission this operation checks: a scoped API key without that scope, an admin without the Account capability that covers it, or, for a node-scoped check, a node outside this Environment",
+                     *         "message": "The caller lacks `api_key.manage` (a scoped API key without that scope, or an admin without the Account capability that covers it), or is a scoped API key acting on a key with more access than its own: a `full_access` key, or one holding a scope outside its own (`api_key.access_exceeds_caller`)",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
-                     *         "path": "/api/v1/api-keys",
-                     *         "method": "GET"
+                     *         "path": "/api/v1/api-keys/{id}",
+                     *         "method": "PATCH"
                      *       }
                      *     }
                      */
@@ -21270,7 +21332,7 @@ interface operations {
                     "application/json": components["schemas"]["ErrorResponseDto"];
                 };
             };
-            /** @description The bearer token is not an admin or platform token, or the caller lacks the permission this operation checks: a scoped API key without that scope, an admin without the Account capability that covers it, or, for a node-scoped check, a node outside this Environment */
+            /** @description The caller lacks `api_key.manage` (a scoped API key without that scope, or an admin without the Account capability that covers it), or is a scoped API key acting on a key with more access than its own: a `full_access` key, or one holding a scope outside its own (`api_key.access_exceeds_caller`) */
             403: {
                 headers: {
                     [name: string]: unknown;
@@ -21281,10 +21343,10 @@ interface operations {
                      *       "error": {
                      *         "statusCode": 403,
                      *         "code": null,
-                     *         "message": "The bearer token is not an admin or platform token, or the caller lacks the permission this operation checks: a scoped API key without that scope, an admin without the Account capability that covers it, or, for a node-scoped check, a node outside this Environment",
+                     *         "message": "The caller lacks `api_key.manage` (a scoped API key without that scope, or an admin without the Account capability that covers it), or is a scoped API key acting on a key with more access than its own: a `full_access` key, or one holding a scope outside its own (`api_key.access_exceeds_caller`)",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
-                     *         "path": "/api/v1/api-keys",
-                     *         "method": "GET"
+                     *         "path": "/api/v1/api-keys/{id}/rotate-secret",
+                     *         "method": "POST"
                      *       }
                      *     }
                      */
@@ -21479,8 +21541,16 @@ declare class Identities {
      * newest first: when and where it was signed in, when it expires, and the
      * organization it is acting in. Read it back after a revoke to confirm,
      * from your own side, that a sign-out took.
+     *
+     * Paginated (20 per page by default, `take` up to 100), so this returns a
+     * `Paginator`: iterate it for every session, or call `.first()` for the
+     * newest. The list takes `page` and `take` only; its order is fixed.
+     *
+     * ```ts
+     * for await (const session of canopy.identities.sessions(id)) { … }
+     * ```
      */
-    sessions(id: string): Promise<ResponseBody<"ApiIdentitiesController_listIdentitySessions">>;
+    sessions(id: string, query?: QueryParams<"ApiIdentitiesController_listIdentitySessions">): Paginator<IdentitySessionItem>;
     /**
      * Ends one session and leaves the identity's others signed in. `sessionId`
      * is the session's `id` from `sessions`: its current refresh token, which
@@ -21608,8 +21678,18 @@ declare class Organizations {
     revokeDirectoryToken(id: string, tokenId: string): Promise<void>;
     /** The organization's own provisioning events, newest first. */
     listDirectoryActivity(id: string): Promise<ResponseBody<"ApiOrganizationDirectoryController_activity">>;
-    /** The groups the provider has pushed, each with its role mapping. */
-    listDirectoryGroups(id: string): Promise<ResponseBody<"ApiOrganizationDirectoryGroupsController_list">>;
+    /**
+     * The groups the provider has pushed, each with its role mapping.
+     *
+     * Paginated (20 per page by default, `take` up to 100), so this returns a
+     * `Paginator`. Sorted by display name unless `sort_by: "created"`; `q`
+     * searches display names and external ids.
+     *
+     * ```ts
+     * for await (const group of canopy.organizations.listDirectoryGroups(id)) { … }
+     * ```
+     */
+    listDirectoryGroups(id: string, query?: QueryParams<"ApiOrganizationDirectoryGroupsController_list">): Paginator<OrganizationDirectoryGroupItem>;
     /**
      * Grant a listed role to every member of a pushed group, at the
      * organization. A role not on the organization's list is refused with
@@ -21622,6 +21702,8 @@ declare class Organizations {
 type OrganizationItem = ItemOf$2<ResponseBody<"ApiOrganizationsController_listOrganizations">>;
 type OrganizationMemberItem = ItemOf$2<ResponseBody<"ApiOrganizationsController_listMembers">>;
 type OrganizationInviteItem = ItemOf$2<ResponseBody<"ApiOrganizationsController_listInvites">>;
+/** One pushed group from an organization's directory. */
+type OrganizationDirectoryGroupItem = ItemOf$2<ResponseBody<"ApiOrganizationDirectoryGroupsController_list">>;
 type ItemOf$2<T> = T extends {
     items: (infer Item)[];
 } ? Item : never;
@@ -21655,6 +21737,10 @@ declare class Permissions {
      *
      * Prefer this to a loop over `evaluate` when rendering a screen: the checks
      * are answered together instead of paying request latency for each.
+     *
+     * One request carries between 1 and 100 checks. More is refused with a
+     * `400` (`CanopyError`, `statusCode` 400) and nothing is evaluated, so split
+     * a larger set into batches of 100.
      */
     evaluateBulk(input: RequestBody<"ApiPermissionsController_evaluateBulk">, options?: CallOptions): Promise<ResponseBody<"ApiPermissionsController_evaluateBulk">>;
     /**
@@ -21792,10 +21878,18 @@ interface LocalAuthorizationQuery {
     node_id?: string;
 }
 interface LocalAuthorizerStats {
-    /** Calls made to read an identity's grant roots. */
+    /** Reads of an identity's grant roots, one per refresh however many pages it took. */
     grantFetches: number;
-    /** Calls made to read the hierarchy, including revalidations. */
+    /** Page requests those reads made: at least one per read, one more per further 100 grants. */
+    grantPages: number;
+    /** Reads of the hierarchy, one per refresh, including revalidations. */
     treeRequests: number;
+    /**
+     * Page requests those reads made: one for a revalidation the server answers
+     * `304`, otherwise one per page of 100 nodes, plus the request that confirms
+     * a walk of several pages was not torn by a change made during it.
+     */
+    treePages: number;
     /** Revalidations the server answered `304`, so no tree was transferred. */
     treeNotModified: number;
 }
@@ -21859,14 +21953,39 @@ declare class LocalAuthorizer {
     /** Climb from `nodeId` and look for a grant root among its ancestors. */
     private holdsAtNode;
     private grantRootsFor;
+    /**
+     * Every page of the identity's grant roots, folded into permission → nodes.
+     *
+     * Each row is one permission at one node, so a permission granted at three
+     * nodes arrives as three rows, possibly on different pages. Stopping after
+     * the first page would under-report what the identity holds: a false deny,
+     * the safe direction, but a wrong answer all the same.
+     */
     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.
+     *
+     * The edges come a page at a time, so only the first page is conditional:
+     * its validator covers the whole hierarchy, and a `304` to it means no page
+     * has changed. On a `200` the remaining pages are read plainly and the map
+     * is rebuilt from every page.
+     *
+     * A walk over several pages is not one snapshot. A node added or removed
+     * between two page reads shifts the rows under the offset, so a row can be
+     * skipped, which would leave a node out of the map until the next refresh.
+     * So the walk is confirmed by asking for the first page again with the
+     * validator it came with: a `304` proves nothing changed while the pages
+     * were read. A `200` is a fresh first page, and the walk starts again from
+     * it, up to {@link MAX_TREE_WALKS} times.
      */
     private fetchTree;
+    private parentsFirstPage;
+    /** The first page's edges followed by every later page's. */
+    private parentsRemainingPages;
+    private keepTree;
 }
 
 /**
@@ -21964,8 +22083,9 @@ declare class CanopyConnectionError extends Error {
  * 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.
+ * codes. Every one but `token.jwks_unavailable` means the same thing to an
+ * HTTP caller, 401; that one means the keys could not be read, so the token may
+ * be good and the answer is 503. {@link tokenErrorStatus} maps them.
  */
 declare class CanopyTokenError extends Error {
     readonly name = "CanopyTokenError";
@@ -21982,6 +22102,8 @@ declare class CanopyTokenError extends Error {
      * - `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
+     * - `token.type_not_allowed` — a principal type the verifier does not accept
+     *   (see `allowedTypes`)
      */
     readonly code: string;
     constructor(code: string, message: string, options?: {
@@ -22013,6 +22135,44 @@ declare function isCanopyError(error: unknown): error is CanopyError;
 declare function isCanopyConnectionError(error: unknown): error is CanopyConnectionError;
 declare function isCanopyTokenError(error: unknown): error is CanopyTokenError;
 
+/**
+ * The HTTP answer a failure should become, for code that verifies tokens or
+ * authorizes requests outside the NestJS guards (Express, Fastify, a worker).
+ * The guards use the same mapping, so every integration answers alike.
+ */
+interface FailureStatus {
+    status: number;
+    /** A message safe to send to the caller; the detail stays on the error. */
+    message: string;
+}
+/**
+ * The answer for a failed {@link TokenVerifier.verify}: `401` when the token is
+ * at fault, `503` when the signing keys could not be read and the token may be
+ * perfectly good.
+ *
+ * The difference matters. A client reads `401` as "your token is stale",
+ * discards a valid one and asks for another, which aims a refresh storm at an
+ * issuer that is already down, and an outage that only emits 4xx is invisible
+ * to anything watching for 5xx.
+ *
+ * Anything that is not a token error is returned as `500`: it is a bug, not a
+ * verdict on the token.
+ */
+declare function tokenErrorStatus(error: unknown): FailureStatus;
+/**
+ * The answer for a failed authorization check ({@link LocalAuthorizer.evaluate}
+ * or a {@link Canopy} call that decides access). Every branch denies; they say
+ * different things so an incident is diagnosable:
+ *
+ * - `500` when the authorizer cannot see far enough to decide (a credential
+ *   that cannot read the hierarchy), when Canopy rejected our own credential,
+ *   when the endpoint is not served (an SDK newer than the API), or on a 4xx
+ *   nobody anticipated. No retry fixes these.
+ * - `503` when Canopy did not answer, or answered 429 or 5xx.
+ * - `403` when Canopy answered that the identity is not in this Environment.
+ */
+declare function authorizationErrorStatus(error: unknown): FailureStatus;
+
 interface TokenVerifierOptions {
     /**
      * The Environment whose tokens are accepted. Every Environment is its own
@@ -22070,6 +22230,16 @@ interface TokenVerifierOptions {
      * request path, so an unbounded read there is an unbounded request.
      */
     jwksTimeoutMs?: number;
+    /**
+     * The principal types accepted, matched against the `type` claim. Defaults to
+     * `["identity"]`: the people who sign in to your application.
+     *
+     * Canopy also signs tokens for its own administrators (`user`), its staff
+     * (`platform`) and, for some flows, API keys (`api_key`), all with the same
+     * keys and issuer. A backend that serves your end users should accept none
+     * of them, so they are refused unless you name them here.
+     */
+    allowedTypes?: ReadonlyArray<CanopyTokenClaims["type"]>;
     /** Injectable for tests and for runtimes with a non-global fetch. */
     fetch?: typeof globalThis.fetch;
 }
@@ -22160,11 +22330,14 @@ declare class TokenVerifier {
     private readonly jwksTimeoutMs;
     private readonly clockToleranceSec;
     private readonly allowPreAuthTokens;
+    private readonly allowedTypes;
     private readonly fetchImpl;
     /** Imported keys by `kid`, so a repeat verification skips the import cost. */
     private keys;
     private keysFetchedAt;
     private lastFetchAttemptAt;
+    /** Whether the latest read of the key set failed, for an unknown `kid`. */
+    private lastFetchFailed;
     /** In-flight fetch, so a burst of requests triggers one call, not N. */
     private inFlight;
     constructor(options?: TokenVerifierOptions);
@@ -22208,6 +22381,7 @@ declare class TokenVerifier {
     private shouldRefresh;
     private refreshKeys;
     private fetchKeys;
+    private readKeys;
 }
 
 /**
@@ -22254,4 +22428,4 @@ type WebhookEventData<Name extends WebhookEventName> = WebhookEvent<Name>["data"
  */
 declare function isWebhookEvent<Name extends WebhookEventName>(delivery: WebhookDelivery, name: Name): delivery is WebhookEvent<Name>;
 
-export { type AssignmentItem, Assignments, type CallOptions, Canopy, CanopyAuthorizerError, CanopyClient, type CanopyClientOptions, CanopyConnectionError, CanopyError, type CanopyErrorBody, type CanopyOrgContext, type CanopyTokenClaims, CanopyTokenError, type Collection, type ConcurrencyOptions, type ConditionalResult, type CursorPagination, Identities, type IdentityAssignmentItem, type IdentityItem, type IdentitySessionItem, type LocalAuthorizationQuery, LocalAuthorizer, type LocalAuthorizerOptions, type LocalAuthorizerStats, MAX_TTL_MS, type OffsetPagination, type OperationId, type OrganizationInviteItem, type OrganizationItem, type OrganizationMemberItem, Organizations, 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 WebhookDelivery, type WebhookEvent, type WebhookEventData, type WebhookEventName, type components, isCanopyAuthorizerError, isCanopyConnectionError, isCanopyError, isCanopyTokenError, isCursorPagination, isWebhookEvent, type operations, orgContext, paginate, type paths, withConcurrency };
+export { type AssignmentItem, Assignments, type CallOptions, Canopy, CanopyAuthorizerError, CanopyClient, type CanopyClientOptions, CanopyConnectionError, CanopyError, type CanopyErrorBody, type CanopyOrgContext, type CanopyTokenClaims, CanopyTokenError, type Collection, type ConcurrencyOptions, type ConditionalResult, type CursorPagination, type FailureStatus, Identities, type IdentityAssignmentItem, type IdentityItem, type IdentitySessionItem, type LocalAuthorizationQuery, LocalAuthorizer, type LocalAuthorizerOptions, type LocalAuthorizerStats, MAX_TTL_MS, type OffsetPagination, type OperationId, type OrganizationDirectoryGroupItem, type OrganizationInviteItem, type OrganizationItem, type OrganizationMemberItem, Organizations, 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 WebhookDelivery, type WebhookEvent, type WebhookEventData, type WebhookEventName, authorizationErrorStatus, type components, isCanopyAuthorizerError, isCanopyConnectionError, isCanopyError, isCanopyTokenError, isCursorPagination, isWebhookEvent, type operations, orgContext, paginate, type paths, tokenErrorStatus, withConcurrency };