npm - @faable/auth-sdk - Versions diffs - 2.9.0 → 2.9.1 - Mend

@faable/auth-sdk 2.9.0 → 2.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/dist/api/generated-client.d.ts +255 -0
package/dist/api/generated-client.js +171 -0
package/dist/api/types.d.ts +1475 -180
package/dist/version.js +2 -2
package/package.json +1 -1
package/spec/openapi.json +2930 -640

package/spec/openapi.json CHANGED Viewed

@@ -3,7 +3,7 @@
   "info": {
     "title": "@faablecloud/auth",
     "description": "Auth Platform made by Faable. Manage Users and Roles",
-    "version": "2.92.1",
+    "version": "2.93.0",
     "license": {
       "name": "private",
       "url": "https://faable.com/docs/platform/privacy-policy"
@@ -4155,6 +4155,7 @@
           "id",
           "name",
           "description",
+          "permissions",
           "account",
           "createdAt"
         ],
@@ -4172,6 +4173,31 @@
             "type": "string",
             "description": "Free-form explanation of what users in this role are expected to do or have access to. Shown alongside the role in the dashboard."
           },
+          "permissions": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "api",
+                "value"
+              ],
+              "properties": {
+                "api": {
+                  "type": "string",
+                  "description": "Id of the Api that defines the permission.",
+                  "example": "api_6555fd293acc2f0fac0e3452"
+                },
+                "value": {
+                  "type": "string",
+                  "description": "The permission, as it appears in the Api's `permissions` catalog.",
+                  "example": "invites:write"
+                }
+              },
+              "additionalProperties": false,
+              "description": "A permission of one Api granted by a role."
+            },
+            "description": "Api permissions granted to the users that hold this role at the account level (team roles grant none). Change them with `POST` / `DELETE /role/:role_id/permissions`; `GET /role/:role_id/permissions` lists them with their Api."
+          },
           "account": {
             "type": "string",
             "description": "Object is related with this account"
@@ -4813,6 +4839,7 @@
           "token_dialect",
           "token_lifetime",
           "enforce_policies",
+          "rbac",
           "allow_offline_access",
           "skip_consent",
           "include_teams_in_access_token",
@@ -4890,317 +4917,329 @@
             "type": "boolean",
             "description": "When true, only scopes that match a permission in `permissions` are forwarded into the access_token. When false, requested scopes are echoed back verbatim with no filtering."
           },
-          "allow_offline_access": {
-            "type": "boolean",
-            "description": "When true, the API is eligible to be the target of a `refresh_token` (i.e. clients can request `offline_access` against it)."
-          },
-          "consent_options": {
-            "type": "object",
-            "required": [
-              "claim",
-              "label",
-              "url",
-              "audience"
-            ],
-            "properties": {
-              "claim": {
-                "type": "string",
-                "pattern": "^[a-z][a-z0-9_]{0,31}$",
-                "description": "Access token claim that carries the chosen id."
-              },
-              "label": {
-                "type": "string",
-                "maxLength": 60,
-                "description": "What the screen asks for, e.g. \"Project\"."
-              },
-              "url": {
-                "type": "string",
-                "pattern": "^https://",
-                "description": "GET endpoint of the resource server that lists the choices."
-              },
-              "audience": {
-                "type": "string",
-                "description": "Identifier of a registered API the listing token is issued for (usually the resource server behind `url`)."
-              },
-              "scope": {
-                "type": "string",
-                "description": "Space-separated permissions of the listing token. The token is delegated (`act`): the resource server sees auth acting for the user with only these, never the user’s full powers — an admin is listed their own choices, not the whole platform’s."
-              }
-            },
-            "nullable": true
-          },
-          "delegation": {
-            "type": "object",
-            "required": [
-              "client_id",
-              "audience"
-            ],
-            "properties": {
-              "client_id": {
-                "type": "string",
-                "description": "The confidential client of the resource server allowed to exchange."
-              },
-              "audience": {
-                "type": "string",
-                "description": "Identifier of the registered API the new token is for."
-              }
-            },
-            "nullable": true
-          },
-          "skip_consent": {
-            "type": "boolean",
-            "description": "When true, the consent prompt is skipped for first-party clients (clients owned by the same tenant as the API)."
-          },
-          "include_teams_in_access_token": {
-            "type": "boolean",
-            "description": "When true, access_tokens issued for this API carry a `teams` claim listing the slugs of the teams the subject is a member of within the tenant."
-          },
-          "include_roles_in_access_token": {
-            "type": "boolean",
-            "description": "When true, access_tokens issued for this API carry a `roles` claim listing the names of the roles the subject holds across their team memberships within the tenant."
-          },
-          "include_teams_in_id_token": {
+          "rbac": {
             "type": "boolean",
-            "description": "When true, id_tokens issued together with an access_token for this API carry a `teams` claim with the subject team slugs. The id_token only sees the flag when the client requested `audience=` so this API is resolved at issuance time."
-          },
-          "include_roles_in_id_token": {
-            "type": "boolean",
-            "description": "When true, id_tokens issued together with an access_token for this API carry a `roles` claim with the subject role names. Same audience caveat as `include_teams_in_id_token`."
-          },
-          "account": {
-            "type": "string",
-            "description": "Object is related with this account"
-          },
-          "metadata": {
-            "type": "object",
-            "properties": {},
-            "additionalProperties": true,
-            "description": "ApiMetadata",
-            "default": {}
-          },
-          "createdAt": {
-            "type": "string",
-            "description": "Api creation date"
-          },
-          "updatedAt": {
-            "type": "string",
-            "description": "Api updated date"
-          }
-        },
-        "description": "Api"
-      },
-      "ApiMetadata": {
-        "type": "object",
-        "properties": {},
-        "additionalProperties": true,
-        "description": "ApiMetadata",
-        "default": {}
-      },
-      "ApiCreate": {
-        "type": "object",
-        "required": [
-          "name",
-          "identifier"
-        ],
-        "properties": {
-          "name": {
-            "type": "string",
-            "description": "Human-readable name for the API.",
-            "example": "My Backend API"
-          },
-          "identifier": {
-            "type": "string",
-            "description": "Audience URL clients pass as `audience=` when requesting a token for this API. Must be unique within the tenant and is immutable after creation.",
-            "example": "https://api.faable.com"
-          },
-          "description": {
-            "type": "string",
-            "description": "Optional human-readable description of the API."
-          },
-          "permissions": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/PermissionCreate"
-            },
-            "description": "Set of permissions (scopes) this API exposes. Tokens issued with `audience=identifier` will only carry these in their `permissions` claim.",
-            "default": []
-          },
-          "signing_alg": {
-            "anyOf": [
-              {
-                "type": "string",
-                "enum": [
-                  "RS256"
-                ]
-              }
-            ],
-            "description": "JWA algorithm used to sign access_tokens issued for this API. Currently only RS256 (the account keystore default) is implemented."
-          },
-          "token_dialect": {
-            "anyOf": [
-              {
-                "type": "string",
-                "enum": [
-                  "access_token"
-                ]
-              },
-              {
-                "type": "string",
-                "enum": [
-                  "access_token_authz"
-                ]
-              }
-            ],
-            "description": "Shape of access_tokens issued for this API. `access_token` emits the standard OAuth2 token. `access_token_authz` additionally embeds a `permissions` claim listing the permissions granted to the subject for this API."
-          },
-          "token_lifetime": {
-            "type": "integer",
-            "description": "Access_token lifetime in seconds. Defaults to 86400 (24h) if omitted.",
-            "minimum": 60,
-            "maximum": 2592000
-          },
-          "enforce_policies": {
-            "type": "boolean",
-            "description": "When true, requested scopes are filtered against `permissions` at token issuance."
+            "description": "Role-based access control. When true, a token issued to a user carries only the permissions of this API granted to the user's roles (account-level role assignments, not team roles): `permissions` lists all of them, and `scope` keeps only the requested ones the user holds. Machine-to-machine tokens (`client_credentials`) are not affected. The `permissions` claim requires `token_dialect: access_token_authz`."
           },
           "allow_offline_access": {
             "type": "boolean",
-            "description": "When true, clients can request `offline_access` and receive a refresh_token for this API."
-          },
-          "consent_options": {
-            "type": "object",
-            "required": [
-              "claim",
-              "label",
-              "url",
-              "audience"
-            ],
-            "properties": {
-              "claim": {
-                "type": "string",
-                "pattern": "^[a-z][a-z0-9_]{0,31}$",
-                "description": "Access token claim that carries the chosen id."
-              },
-              "label": {
-                "type": "string",
-                "maxLength": 60,
-                "description": "What the screen asks for, e.g. \"Project\"."
-              },
-              "url": {
-                "type": "string",
-                "pattern": "^https://",
-                "description": "GET endpoint of the resource server that lists the choices."
-              },
-              "audience": {
-                "type": "string",
-                "description": "Identifier of a registered API the listing token is issued for (usually the resource server behind `url`)."
-              },
-              "scope": {
-                "type": "string",
-                "description": "Space-separated permissions of the listing token. The token is delegated (`act`): the resource server sees auth acting for the user with only these, never the user’s full powers — an admin is listed their own choices, not the whole platform’s."
-              }
-            }
-          },
-          "delegation": {
-            "type": "object",
-            "required": [
-              "client_id",
-              "audience"
-            ],
-            "properties": {
-              "client_id": {
-                "type": "string",
-                "description": "The confidential client of the resource server allowed to exchange."
-              },
-              "audience": {
-                "type": "string",
-                "description": "Identifier of the registered API the new token is for."
-              }
-            }
-          },
-          "skip_consent": {
-            "type": "boolean",
-            "description": "When true, skip the consent prompt for first-party clients."
-          },
-          "include_teams_in_access_token": {
-            "type": "boolean",
-            "description": "When true, access_tokens issued for this API carry a `teams` claim with the subject team slugs."
-          },
-          "include_roles_in_access_token": {
-            "type": "boolean",
-            "description": "When true, access_tokens issued for this API carry a `roles` claim with the subject role names."
-          },
-          "include_teams_in_id_token": {
-            "type": "boolean",
-            "description": "When true, id_tokens issued together with an access_token for this API carry a `teams` claim with the subject team slugs."
-          },
-          "include_roles_in_id_token": {
-            "type": "boolean",
-            "description": "When true, id_tokens issued together with an access_token for this API carry a `roles` claim with the subject role names."
-          }
-        },
-        "additionalProperties": false,
-        "description": "Payload for creating an Api (a.k.a. Resource Server / Audience). The `identifier` becomes the `aud` claim in tokens issued for this API and cannot be changed after creation."
-      },
-      "ApiUpdate": {
-        "type": "object",
-        "properties": {
-          "name": {
-            "type": "string",
-            "description": "Human-readable name for the API."
-          },
-          "description": {
-            "type": "string",
-            "description": "Optional human-readable description of the API."
-          },
-          "permissions": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/PermissionCreate"
-            },
-            "description": "Replaces the full permissions list. Tokens issued AFTER the update will use the new list; tokens already in circulation are unchanged."
-          },
-          "signing_alg": {
-            "anyOf": [
-              {
-                "type": "string",
-                "enum": [
-                  "RS256"
-                ]
-              }
-            ],
-            "description": "JWA algorithm used to sign access_tokens issued for this API. Currently only RS256 (the account keystore default) is implemented."
-          },
-          "token_dialect": {
-            "anyOf": [
-              {
-                "type": "string",
-                "enum": [
-                  "access_token"
-                ]
-              },
-              {
-                "type": "string",
-                "enum": [
-                  "access_token_authz"
-                ]
-              }
-            ],
-            "description": "Shape of access_tokens issued for this API. `access_token` emits the standard OAuth2 token. `access_token_authz` additionally embeds a `permissions` claim listing the permissions granted to the subject for this API."
-          },
-          "token_lifetime": {
-            "type": "integer",
-            "description": "Access_token lifetime in seconds.",
-            "minimum": 60,
-            "maximum": 2592000
-          },
-          "enforce_policies": {
-            "type": "boolean",
-            "description": "When true, requested scopes are filtered against `permissions` at token issuance."
-          },
-          "allow_offline_access": {
-            "type": "boolean",
-            "description": "When true, clients can request `offline_access` and receive a refresh_token for this API."
+            "description": "When true, the API is eligible to be the target of a `refresh_token` (i.e. clients can request `offline_access` against it)."
+          },
+          "consent_options": {
+            "type": "object",
+            "required": [
+              "claim",
+              "label",
+              "url",
+              "audience"
+            ],
+            "properties": {
+              "claim": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9_]{0,31}$",
+                "description": "Access token claim that carries the chosen id."
+              },
+              "label": {
+                "type": "string",
+                "maxLength": 60,
+                "description": "What the screen asks for, e.g. \"Project\"."
+              },
+              "url": {
+                "type": "string",
+                "pattern": "^https://",
+                "description": "GET endpoint of the resource server that lists the choices."
+              },
+              "audience": {
+                "type": "string",
+                "description": "Identifier of a registered API the listing token is issued for (usually the resource server behind `url`)."
+              },
+              "scope": {
+                "type": "string",
+                "description": "Space-separated permissions of the listing token. The token is delegated (`act`): the resource server sees auth acting for the user with only these, never the user’s full powers — an admin is listed their own choices, not the whole platform’s."
+              }
+            },
+            "nullable": true
+          },
+          "delegation": {
+            "type": "object",
+            "required": [
+              "client_id",
+              "audience"
+            ],
+            "properties": {
+              "client_id": {
+                "type": "string",
+                "description": "The confidential client of the resource server allowed to exchange."
+              },
+              "audience": {
+                "type": "string",
+                "description": "Identifier of the registered API the new token is for."
+              }
+            },
+            "nullable": true
+          },
+          "skip_consent": {
+            "type": "boolean",
+            "description": "When true, the consent prompt is skipped for first-party clients (clients owned by the same tenant as the API)."
+          },
+          "include_teams_in_access_token": {
+            "type": "boolean",
+            "description": "When true, access_tokens issued for this API carry a `teams` claim listing the slugs of the teams the subject is a member of within the tenant."
+          },
+          "include_roles_in_access_token": {
+            "type": "boolean",
+            "description": "When true, access_tokens issued for this API carry a `roles` claim listing the names of the roles the subject holds across their team memberships within the tenant."
+          },
+          "include_teams_in_id_token": {
+            "type": "boolean",
+            "description": "When true, id_tokens issued together with an access_token for this API carry a `teams` claim with the subject team slugs. The id_token only sees the flag when the client requested `audience=` so this API is resolved at issuance time."
+          },
+          "include_roles_in_id_token": {
+            "type": "boolean",
+            "description": "When true, id_tokens issued together with an access_token for this API carry a `roles` claim with the subject role names. Same audience caveat as `include_teams_in_id_token`."
+          },
+          "account": {
+            "type": "string",
+            "description": "Object is related with this account"
+          },
+          "metadata": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": true,
+            "description": "ApiMetadata",
+            "default": {}
+          },
+          "createdAt": {
+            "type": "string",
+            "description": "Api creation date"
+          },
+          "updatedAt": {
+            "type": "string",
+            "description": "Api updated date"
+          }
+        },
+        "description": "Api"
+      },
+      "ApiMetadata": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": true,
+        "description": "ApiMetadata",
+        "default": {}
+      },
+      "ApiCreate": {
+        "type": "object",
+        "required": [
+          "name",
+          "identifier"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Human-readable name for the API.",
+            "example": "My Backend API"
+          },
+          "identifier": {
+            "type": "string",
+            "description": "Audience URL clients pass as `audience=` when requesting a token for this API. Must be unique within the tenant and is immutable after creation.",
+            "example": "https://api.faable.com"
+          },
+          "description": {
+            "type": "string",
+            "description": "Optional human-readable description of the API."
+          },
+          "permissions": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PermissionCreate"
+            },
+            "description": "Set of permissions (scopes) this API exposes. Tokens issued with `audience=identifier` will only carry these in their `permissions` claim.",
+            "default": []
+          },
+          "signing_alg": {
+            "anyOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "RS256"
+                ]
+              }
+            ],
+            "description": "JWA algorithm used to sign access_tokens issued for this API. Currently only RS256 (the account keystore default) is implemented."
+          },
+          "token_dialect": {
+            "anyOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "access_token"
+                ]
+              },
+              {
+                "type": "string",
+                "enum": [
+                  "access_token_authz"
+                ]
+              }
+            ],
+            "description": "Shape of access_tokens issued for this API. `access_token` emits the standard OAuth2 token. `access_token_authz` additionally embeds a `permissions` claim listing the permissions granted to the subject for this API."
+          },
+          "token_lifetime": {
+            "type": "integer",
+            "description": "Access_token lifetime in seconds. Defaults to 86400 (24h) if omitted.",
+            "minimum": 60,
+            "maximum": 2592000
+          },
+          "enforce_policies": {
+            "type": "boolean",
+            "description": "When true, requested scopes are filtered against `permissions` at token issuance."
+          },
+          "rbac": {
+            "type": "boolean",
+            "description": "When true, user tokens carry only the permissions granted to the user's roles. Defaults to false."
+          },
+          "allow_offline_access": {
+            "type": "boolean",
+            "description": "When true, clients can request `offline_access` and receive a refresh_token for this API."
+          },
+          "consent_options": {
+            "type": "object",
+            "required": [
+              "claim",
+              "label",
+              "url",
+              "audience"
+            ],
+            "properties": {
+              "claim": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9_]{0,31}$",
+                "description": "Access token claim that carries the chosen id."
+              },
+              "label": {
+                "type": "string",
+                "maxLength": 60,
+                "description": "What the screen asks for, e.g. \"Project\"."
+              },
+              "url": {
+                "type": "string",
+                "pattern": "^https://",
+                "description": "GET endpoint of the resource server that lists the choices."
+              },
+              "audience": {
+                "type": "string",
+                "description": "Identifier of a registered API the listing token is issued for (usually the resource server behind `url`)."
+              },
+              "scope": {
+                "type": "string",
+                "description": "Space-separated permissions of the listing token. The token is delegated (`act`): the resource server sees auth acting for the user with only these, never the user’s full powers — an admin is listed their own choices, not the whole platform’s."
+              }
+            }
+          },
+          "delegation": {
+            "type": "object",
+            "required": [
+              "client_id",
+              "audience"
+            ],
+            "properties": {
+              "client_id": {
+                "type": "string",
+                "description": "The confidential client of the resource server allowed to exchange."
+              },
+              "audience": {
+                "type": "string",
+                "description": "Identifier of the registered API the new token is for."
+              }
+            }
+          },
+          "skip_consent": {
+            "type": "boolean",
+            "description": "When true, skip the consent prompt for first-party clients."
+          },
+          "include_teams_in_access_token": {
+            "type": "boolean",
+            "description": "When true, access_tokens issued for this API carry a `teams` claim with the subject team slugs."
+          },
+          "include_roles_in_access_token": {
+            "type": "boolean",
+            "description": "When true, access_tokens issued for this API carry a `roles` claim with the subject role names."
+          },
+          "include_teams_in_id_token": {
+            "type": "boolean",
+            "description": "When true, id_tokens issued together with an access_token for this API carry a `teams` claim with the subject team slugs."
+          },
+          "include_roles_in_id_token": {
+            "type": "boolean",
+            "description": "When true, id_tokens issued together with an access_token for this API carry a `roles` claim with the subject role names."
+          }
+        },
+        "additionalProperties": false,
+        "description": "Payload for creating an Api (a.k.a. Resource Server / Audience). The `identifier` becomes the `aud` claim in tokens issued for this API and cannot be changed after creation."
+      },
+      "ApiUpdate": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Human-readable name for the API."
+          },
+          "description": {
+            "type": "string",
+            "description": "Optional human-readable description of the API."
+          },
+          "permissions": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PermissionCreate"
+            },
+            "description": "Replaces the full permissions list. Tokens issued AFTER the update will use the new list; tokens already in circulation are unchanged."
+          },
+          "signing_alg": {
+            "anyOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "RS256"
+                ]
+              }
+            ],
+            "description": "JWA algorithm used to sign access_tokens issued for this API. Currently only RS256 (the account keystore default) is implemented."
+          },
+          "token_dialect": {
+            "anyOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "access_token"
+                ]
+              },
+              {
+                "type": "string",
+                "enum": [
+                  "access_token_authz"
+                ]
+              }
+            ],
+            "description": "Shape of access_tokens issued for this API. `access_token` emits the standard OAuth2 token. `access_token_authz` additionally embeds a `permissions` claim listing the permissions granted to the subject for this API."
+          },
+          "token_lifetime": {
+            "type": "integer",
+            "description": "Access_token lifetime in seconds.",
+            "minimum": 60,
+            "maximum": 2592000
+          },
+          "enforce_policies": {
+            "type": "boolean",
+            "description": "When true, requested scopes are filtered against `permissions` at token issuance."
+          },
+          "rbac": {
+            "type": "boolean",
+            "description": "When true, user tokens carry only the permissions granted to the user's roles. Applies to tokens issued after the update, including refreshes."
+          },
+          "allow_offline_access": {
+            "type": "boolean",
+            "description": "When true, clients can request `offline_access` and receive a refresh_token for this API."
           },
           "consent_options": {
             "type": "object",
@@ -9657,7 +9696,7 @@
       },
       "ErrorCode": {
         "type": "string",
-        "description": "Machine-readable error code. One HTTP status per code.\n\n- `bad_request` (400): The request is malformed. `message` says what is wrong.\n- `validation_error` (400): The body, query or path failed schema validation. `details.issues` lists each failing field.\n- `unauthorized` (401): The request carries no valid credentials.\n- `payment_required` (402): The feature is not included in the current plan.\n- `forbidden` (403): The credentials are valid but do not allow this operation.\n- `not_found` (404): The resource does not exist in this account.\n- `method_not_allowed` (405): The HTTP method is not supported on this path.\n- `conflict` (409): The request conflicts with the current state of the resource.\n- `last_sign_in_method` (409): Unlinking this account would leave the user with no way to sign in: set a password, verify the email or link another account first.\n- `payload_too_large` (413): The request body exceeds the size limit.\n- `unsupported_media_type` (415): The `Content-Type` is not accepted by this endpoint.\n- `unprocessable_entity` (422): The request is well-formed but cannot be processed.\n- `too_many_requests` (429): Rate limit exceeded. Honour the `Retry-After` header.\n- `internal_error` (500): Unexpected server error. Retry later; the request id is logged.\n- `already_exists` (400): A resource with the same unique field already exists (for a user, usually `email`). `details.fields` names the field.\n- `invalid_id` (400): The id in the path is not a valid id for this resource.\n- `account_not_found` (404): No Auth Account matches the request (domain, header or token).\n- `invalid_query` (400): The `?query=` FaableQL expression could not be parsed.\n- `search_not_supported` (400): This resource does not support `?search=`.\n- `invalid_expand` (400): An `?expand=` path is not allowed on this resource.\n- `access_denied` (403): The caller may not access this row (ownership or machine-to-machine restriction).\n- `insufficient_scope` (403): The token lacks a scope this operation requires. `message` names it.\n- `team_required` (400): An Auth Account must belong to a project (team).\n- `account_limit_reached` (409): The project already has the maximum number of Auth Accounts.\n- `invalid_project_id` (400): The project id is not of the form `project_<hex>` or `team_<hex>`.\n- `account_transfer_refused` (409): The Auth Account cannot be moved to that project. `details.blockers` lists why.\n- `email_sender_domain_not_allowed` (400): The sender address is not in a domain this platform signs email for (AUTH_EMAIL_SENDER_DOMAINS).\n- `plan_required` (402): The setting requires a higher plan. `message` says which.\n- `invalid_canonical_host` (400): `canonical_host` must be this account's own platform host or one of its verified custom domains.\n- `canonical_host_breaks_passkeys` (400): `canonical_host` is outside the account's current WebAuthn RP ID — every passkey already enrolled would stop working. Set `webauthn_rp_id` in the same request to a suffix that covers both.\n- `not_logged_in` (401): There is no signed-in session for this request.\n- `session_already_revoked` (409): The session was already revoked.\n- `invalid_token` (401): The bearer token is missing, malformed, expired or has no subject.\n- `not_owner` (403): The caller may only perform this operation on their own user.\n- `user_suspended` (403): The user is suspended and cannot sign in or be modified.\n- `invalid_credentials` (400): The email/username or password is incorrect.\n- `login_denied` (401): A post-login Action denied the sign-in. `message` carries the reason it gave. On token grants it is a 403 with `error: invalid_grant`.\n- `signup_denied` (403): A pre-signup Action or an active block denied the sign-up. `message` carries the reason.\n- `client_credentials_denied` (401): An Action denied the client_credentials grant. `message` carries the reason.\n- `m2m_quota_exceeded` (402): The project used the machine-to-machine tokens its plan includes this month. Free is capped; Hobby and Pro are billed per token instead.\n- `signup_disabled` (403): Self-service sign-up is disabled on this connection.\n- `email_taken` (409): Another user in this account already uses that email.\n- `username_taken` (409): Another user of this database connection already uses that username.\n- `invalid_username` (400): The username is empty, or contains an `@` or whitespace. `message` says which.\n- `invalid_email` (400): The email address is not valid.\n- `invalid_name` (400): The name contains a link. `message` says which field.\n- `same_email` (400): The new email is the same as the current one.\n- `user_has_no_email` (400): The operation needs an email but the user has none.\n- `password_too_weak` (400): The password does not meet the connection policy. `message` lists each unmet rule.\n- `invalid_password_hash` (400): The imported password hash cannot be read, or its cost is above what a login can afford. `message` names the field.\n- `weak_password_hash` (400): The imported password hash uses a fast digest (MD5, SHA-1, SHA-2) or a cost below the minimum. `message` says which.\n- `invalid_code` (400): The verification code is wrong, expired or already used.\n- `invalid_phone` (400): The phone number is not E.164 and could not be resolved with the account default country. Include the country code.\n- `phone_changed` (400): The phone on the user changed after the code was sent. Start again.\n- `phone_already_verified` (409): The user already has a verified phone; the number cannot be swapped from the screen.\n- `sms_unavailable` (409): This account cannot send SMS right now. The suffix says why: `sms_unavailable:plan`, `:quota`, `:provider`.\n- `sms_failed` (409): The SMS provider rejected the message.\n- `invalid_state` (400): The `state` is missing, expired, or does not describe a resumable step.\n- `state_mismatch` (401): The `state` belongs to another account, session, client or ceremony.\n- `invalid_ticket` (400): The ticket does not exist or is not the kind this endpoint accepts.\n- `ticket_used` (400): The ticket was already consumed.\n- `ticket_expired` (400): The ticket is past its expiry.\n- `ticket_not_found` (404): No ticket with that id belongs to this user.\n- `credential_not_found` (404): The user has no password credential on this connection.\n- `invalid_link` (400): The magic link is malformed.\n- `expired_link` (400): The magic link token was not found or has expired.\n- `invalid_otp` (401): The one-time password is wrong or expired.\n- `invalid_client` (400): The `client_id` in the request does not name a client of this account.\n- `client_not_found` (404): No client with that `client_id`.\n- `client_mismatch` (401): The client belongs to a different account.\n- `invalid_client_metadata` (400): Dynamic client registration rejected a field (RFC 7591). `message` names it.\n- `invalid_connection` (400): The connection does not exist, is disabled, or is not of the type this flow needs.\n- `no_database_connection` (400): The tenant has no database connection, so there is nowhere to store a password. Create one and retry.\n- `connection_required` (400): No connection was given and the client has no `default_connection`.\n- `connection_misconfigured` (400): The connection is missing settings needed to talk to its provider.\n- `passwordless_unavailable` (400): No passwordless connection is configured or enabled for this client.\n- `ambiguous_connection` (400): Several connections match; pass `connection_id`.\n- `invalid_redirect_uri` (400): The redirect URI is not registered for the client.\n- `invalid_saml_request` (400): The SAMLRequest is missing, too large, not well-formed or not a SAML 2.0 AuthnRequest.\n- `saml_sp_mismatch` (400): The AuthnRequest does not match the client's SAML configuration: its Issuer is not the configured entity_id, or it asks for another Assertion Consumer Service URL or binding.\n- `saml_not_enabled` (404): This client does not have SAML enabled.\n- `invalid_saml_sp` (400): The `saml_sp` configuration is invalid: `acs_url` must be an absolute https URL without a fragment.\n- `origin_not_allowed` (403): The request `Origin` is not in the client's Allowed Web Origins.\n- `audience_not_found` (403): The `audience` does not name an API registered in this account.\n- `system_resource` (403): The resource is managed by Faable and cannot be modified or deleted.\n- `invalid_request` (400): A required OAuth parameter is missing or two of them are incompatible. `message` says which.\n- `invalid_device_code` (400): The device or user code is invalid or expired.\n- `provider_error` (400): The upstream identity provider returned an error. The suffix is the provider’s own code, when it sent one: `provider_error:bad_refresh_token` (the user must re-authorize), `provider_error:incorrect_client_credentials` (our configuration, the user can do nothing). `details.provider_error_description` carries the provider’s sentence.\n- `identity_already_linked` (409): That external identity is already linked to another user.\n- `identity_link_denied` (409): That external identity cannot be linked to this user.\n- `identity_conflict` (409): The user already has a linked identity for this connection.\n- `identity_orphaned` (400): The identity pointed at a user that no longer exists; it was removed. Sign in again.\n- `no_provider_token` (400): The identity holds no provider access token.\n- `no_refresh_token` (400): The identity holds no provider refresh token, so it cannot be refreshed.\n- `action_unavailable` (401): The Action that paused this login is disabled or belongs elsewhere.\n- `login_flow_misconfigured` (500): The login flow of this account cannot run. `message` carries the node error.\n- `mfa_required` (403): The login needs a second factor that this flow cannot collect, or one is still pending on the session.\n- `step_up_required` (403): Confirm an existing factor before changing your factors.\n- `reauth_required` (403): The operation needs a recent sign-in (and the second factor, when the user has one). Sign in again with `max_age=0` and retry with the new token.\n- `invalid_current_password` (400): The current password is wrong.\n- `email_not_verified` (403): The user's email is not verified, and the operation needs it to be.\n- `invalid_profile_field` (400): A profile field is not declared for this application, or its value does not match the declaration. `message` names the key.\n- `interaction_required` (403): An Action asked for a redirect on a non-interactive flow.\n- `passkey_login_disabled` (400): Sign in with a passkey is not enabled for this client.\n- `mfa_pending` (401): A second-factor challenge is pending; answer it before continuing.\n- `mfa_invalid_code` (401): The authenticator code did not verify.\n- `mfa_invalid_recovery_code` (401): The recovery code did not verify.\n- `too_many_attempts` (429): Too many wrong codes. Wait a few minutes and try again.\n- `too_many_login_attempts` (429): Too many failed sign-in attempts for this email or username from this network. Wait a few minutes and try again.\n- `totp_not_allowed` (401): This account does not accept authenticator apps.\n- `no_usable_factor` (400): The user has no confirmed second factor to challenge.\n- `factor_not_found` (400): No factor with that id belongs to this user.\n- `factor_already_confirmed` (400): The factor was already confirmed.\n- `invalid_factor` (400): The factor cannot be verified (no secret material).\n- `session_missing` (401): The session that started this login no longer exists.\n- `passkey_verification_failed` (400): The WebAuthn response could not be verified.\n- `no_passkey_enrolled` (400): The user has no passkey to sign in with.\n- `malformed_credential` (400): The WebAuthn credential is malformed.\n- `unknown_passkey` (401): The passkey is not enrolled for this user.\n- `invalid_passkey` (401): The passkey assertion did not verify.\n- `invalid_invite_url` (400): An invite's `accept_url` or `redirect_uri` is not an http(s) URL at an origin of this tenant's client callbacks or `callback_hostnames`, or it carries a fragment.\n- `invite_email_mismatch` (403): The invite is for another email address than the accepting user's. `details.invited_email` shows it masked.\n- `invite_email_unverified` (403): The accepting user's email matches the invite but is not verified yet.\n- `invite_not_found` (404): No invite with that id in this account.\n- `invite_used` (400): The invite was already accepted.\n- `already_member` (400): The user is already a member of the team.\n- `not_a_member` (404): The user is not a member of the team.\n- `consent_options_unavailable` (502): The consent screen could not load the choices from the API being authorized (its `consent_options.url`). Try again in a moment.\n- `consent_choice_invalid` (400): The choice sent with the consent decision is not one the API offered for this user.\n- `registration_disabled` (403): Dynamic client registration is turned off for this tenant. Create the client from the dashboard or the Management API, or turn on `dynamic_client_registration_enabled`.\n- `invalid_email_domain` (400): Not an email domain this organization can claim: it must be a plain domain name (`acme.com`), lowercase, without scheme, path or wildcard.\n- `public_email_domain` (400): A public email provider (gmail.com, outlook.com…) cannot belong to an organization: anyone can have an address there.\n- `organization_domain_not_found` (404): The organization has no such domain.\n- `organization_domain_taken` (409): Another organization of this tenant already verified this domain. A domain belongs to one organization.\n- `organization_domain_unverified` (400): The TXT record was not found or does not hold the expected value yet. `details.record` says what was expected and what resolves now; DNS can take a few minutes to propagate.\n- `plan_unavailable` (503): The plan could not be checked right now, and this setting is only for paid plans. Try again in a minute.\n- `organization_domain_mismatch` (403): This organization's identity provider can only sign in addresses of the organization's verified email domains.\n- `team_not_in_organization` (400): Auto-join can only put people in teams of the same organization. `details.teams` lists the others.\n- `organization_has_no_idp` (400): Requiring SSO needs an identity provider: bind an `oidc` connection to the organization first.\n- `organization_not_found` (404): No organization with that id in this account.\n- `invalid_user` (400): The user does not exist in this account.\n- `not_an_organization_admin` (404): The user is not an admin of the organization.\n- `last_organization_admin` (409): An organization keeps at least one admin. Add another admin before removing this one.\n- `team_id_unavailable` (409): The team id cannot be used in this tenant. Pick another id or let the API generate one.\n- `use_team_member_route` (400): This generic route cannot create memberships. Use `POST /team/{team_id}/member` for team members or `POST /role/{role_id}/users` for role grants.\n- `role_not_found` (404): No role with that id in this account.\n- `invalid_role` (400): The role belongs to another account.\n- `flow_not_found` (400): The login flow does not exist in this account.\n- `revision_not_found` (404): The revision is not in the flow history.\n- `invalid_webhook_event` (400): An event is not in the webhook event catalog. `message` and `details.valid_events` list the valid ones.\n- `invalid_webhook_url` (400): The webhook URL must be an absolute `https` URL.\n- `not_a_webhook` (400): The operation only applies to `webhook` subscriptions.\n- `delivery_not_found` (404): No webhook delivery with that id for this subscription.\n- `delivery_in_progress` (409): The delivery is being attempted right now; retry the redeliver in a minute.",
+        "description": "Machine-readable error code. One HTTP status per code.\n\n- `bad_request` (400): The request is malformed. `message` says what is wrong.\n- `validation_error` (400): The body, query or path failed schema validation. `details.issues` lists each failing field.\n- `unauthorized` (401): The request carries no valid credentials.\n- `payment_required` (402): The feature is not included in the current plan.\n- `forbidden` (403): The credentials are valid but do not allow this operation.\n- `not_found` (404): The resource does not exist in this account.\n- `method_not_allowed` (405): The HTTP method is not supported on this path.\n- `conflict` (409): The request conflicts with the current state of the resource.\n- `last_sign_in_method` (409): Unlinking this account would leave the user with no way to sign in: set a password, verify the email or link another account first.\n- `payload_too_large` (413): The request body exceeds the size limit.\n- `unsupported_media_type` (415): The `Content-Type` is not accepted by this endpoint.\n- `unprocessable_entity` (422): The request is well-formed but cannot be processed.\n- `too_many_requests` (429): Rate limit exceeded. Honour the `Retry-After` header.\n- `internal_error` (500): Unexpected server error. Retry later; the request id is logged.\n- `already_exists` (400): A resource with the same unique field already exists (for a user, usually `email`). `details.fields` names the field.\n- `invalid_id` (400): The id in the path is not a valid id for this resource.\n- `account_not_found` (404): No Auth Account matches the request (domain, header or token).\n- `invalid_query` (400): The `?query=` FaableQL expression could not be parsed.\n- `search_not_supported` (400): This resource does not support `?search=`.\n- `invalid_expand` (400): An `?expand=` path is not allowed on this resource.\n- `access_denied` (403): The caller may not access this row (ownership or machine-to-machine restriction).\n- `insufficient_scope` (403): The token lacks a scope this operation requires. `message` names it.\n- `team_required` (400): An Auth Account must belong to a project (team).\n- `account_limit_reached` (409): The project already has the maximum number of Auth Accounts.\n- `invalid_project_id` (400): The project id is not of the form `project_<hex>` or `team_<hex>`.\n- `account_transfer_refused` (409): The Auth Account cannot be moved to that project. `details.blockers` lists why.\n- `email_sender_domain_not_allowed` (400): The sender address is not in a domain this platform signs email for (AUTH_EMAIL_SENDER_DOMAINS).\n- `plan_required` (402): The setting requires a higher plan. `message` says which.\n- `invalid_canonical_host` (400): `canonical_host` must be this account's own platform host or one of its verified custom domains.\n- `canonical_host_breaks_passkeys` (400): `canonical_host` is outside the account's current WebAuthn RP ID — every passkey already enrolled would stop working. Set `webauthn_rp_id` in the same request to a suffix that covers both.\n- `not_logged_in` (401): There is no signed-in session for this request.\n- `session_already_revoked` (409): The session was already revoked.\n- `invalid_token` (401): The bearer token is missing, malformed, expired or has no subject.\n- `not_owner` (403): The caller may only perform this operation on their own user.\n- `user_suspended` (403): The user is suspended and cannot sign in or be modified.\n- `invalid_credentials` (400): The email/username or password is incorrect.\n- `login_denied` (401): A post-login Action denied the sign-in. `message` carries the reason it gave. On token grants it is a 403 with `error: invalid_grant`.\n- `signup_denied` (403): A pre-signup Action or an active block denied the sign-up. `message` carries the reason.\n- `client_credentials_denied` (401): An Action denied the client_credentials grant. `message` carries the reason.\n- `m2m_quota_exceeded` (402): The project used the machine-to-machine tokens its plan includes this month. Free is capped; Hobby and Pro are billed per token instead.\n- `signup_disabled` (403): Self-service sign-up is disabled on this connection.\n- `email_taken` (409): Another user in this account already uses that email.\n- `username_taken` (409): Another user of this database connection already uses that username.\n- `invalid_username` (400): The username is empty, or contains an `@` or whitespace. `message` says which.\n- `invalid_email` (400): The email address is not valid.\n- `invalid_name` (400): The name contains a link. `message` says which field.\n- `same_email` (400): The new email is the same as the current one.\n- `user_has_no_email` (400): The operation needs an email but the user has none.\n- `password_too_weak` (400): The password does not meet the connection policy. `message` lists each unmet rule.\n- `invalid_password_hash` (400): The imported password hash cannot be read, or its cost is above what a login can afford. `message` names the field.\n- `weak_password_hash` (400): The imported password hash uses a fast digest (MD5, SHA-1, SHA-2) or a cost below the minimum. `message` says which.\n- `invalid_code` (400): The verification code is wrong, expired or already used.\n- `invalid_phone` (400): The phone number is not E.164 and could not be resolved with the account default country. Include the country code.\n- `phone_changed` (400): The phone on the user changed after the code was sent. Start again.\n- `phone_already_verified` (409): The user already has a verified phone; the number cannot be swapped from the screen.\n- `sms_unavailable` (409): This account cannot send SMS right now. The suffix says why: `sms_unavailable:plan`, `:quota`, `:provider`.\n- `sms_failed` (409): The SMS provider rejected the message.\n- `invalid_state` (400): The `state` is missing, expired, or does not describe a resumable step.\n- `state_mismatch` (401): The `state` belongs to another account, session, client or ceremony.\n- `invalid_ticket` (400): The ticket does not exist or is not the kind this endpoint accepts.\n- `ticket_used` (400): The ticket was already consumed.\n- `ticket_expired` (400): The ticket is past its expiry.\n- `ticket_not_found` (404): No ticket with that id belongs to this user.\n- `credential_not_found` (404): The user has no password credential on this connection.\n- `invalid_link` (400): The magic link is malformed.\n- `expired_link` (400): The magic link token was not found or has expired.\n- `invalid_otp` (401): The one-time password is wrong or expired.\n- `invalid_client` (400): The `client_id` in the request does not name a client of this account.\n- `client_not_found` (404): No client with that `client_id`.\n- `client_mismatch` (401): The client belongs to a different account.\n- `invalid_client_metadata` (400): Dynamic client registration rejected a field (RFC 7591). `message` names it.\n- `invalid_connection` (400): The connection does not exist, is disabled, or is not of the type this flow needs.\n- `no_database_connection` (400): The tenant has no database connection, so there is nowhere to store a password. Create one and retry.\n- `connection_required` (400): No connection was given and the client has no `default_connection`.\n- `connection_misconfigured` (400): The connection is missing settings needed to talk to its provider.\n- `passwordless_unavailable` (400): No passwordless connection is configured or enabled for this client.\n- `ambiguous_connection` (400): Several connections match; pass `connection_id`.\n- `invalid_redirect_uri` (400): The redirect URI is not registered for the client.\n- `invalid_saml_request` (400): The SAMLRequest is missing, too large, not well-formed or not a SAML 2.0 AuthnRequest.\n- `saml_sp_mismatch` (400): The AuthnRequest does not match the client's SAML configuration: its Issuer is not the configured entity_id, or it asks for another Assertion Consumer Service URL or binding.\n- `saml_not_enabled` (404): This client does not have SAML enabled.\n- `invalid_saml_sp` (400): The `saml_sp` configuration is invalid: `acs_url` must be an absolute https URL without a fragment.\n- `origin_not_allowed` (403): The request `Origin` is not in the client's Allowed Web Origins.\n- `audience_not_found` (403): The `audience` does not name an API registered in this account.\n- `system_resource` (403): The resource is managed by Faable and cannot be modified or deleted.\n- `invalid_request` (400): A required OAuth parameter is missing or two of them are incompatible. `message` says which.\n- `invalid_device_code` (400): The device or user code is invalid or expired.\n- `provider_error` (400): The upstream identity provider returned an error. The suffix is the provider’s own code, when it sent one: `provider_error:bad_refresh_token` (the user must re-authorize), `provider_error:incorrect_client_credentials` (our configuration, the user can do nothing). `details.provider_error_description` carries the provider’s sentence.\n- `identity_already_linked` (409): That external identity is already linked to another user.\n- `identity_link_denied` (409): That external identity cannot be linked to this user.\n- `identity_conflict` (409): The user already has a linked identity for this connection.\n- `identity_orphaned` (400): The identity pointed at a user that no longer exists; it was removed. Sign in again.\n- `no_provider_token` (400): The identity holds no provider access token.\n- `no_refresh_token` (400): The identity holds no provider refresh token, so it cannot be refreshed.\n- `action_unavailable` (401): The Action that paused this login is disabled or belongs elsewhere.\n- `login_flow_misconfigured` (500): The login flow of this account cannot run. `message` carries the node error.\n- `mfa_required` (403): The login needs a second factor that this flow cannot collect, or one is still pending on the session.\n- `step_up_required` (403): Confirm an existing factor before changing your factors.\n- `reauth_required` (403): The operation needs a recent sign-in (and the second factor, when the user has one). Sign in again with `max_age=0` and retry with the new token.\n- `invalid_current_password` (400): The current password is wrong.\n- `email_not_verified` (403): The user's email is not verified, and the operation needs it to be.\n- `invalid_profile_field` (400): A profile field is not declared for this application, or its value does not match the declaration. `message` names the key.\n- `interaction_required` (403): An Action asked for a redirect on a non-interactive flow.\n- `passkey_login_disabled` (400): Sign in with a passkey is not enabled for this client.\n- `mfa_pending` (401): A second-factor challenge is pending; answer it before continuing.\n- `mfa_invalid_code` (401): The authenticator code did not verify.\n- `mfa_invalid_recovery_code` (401): The recovery code did not verify.\n- `too_many_attempts` (429): Too many wrong codes. Wait a few minutes and try again.\n- `too_many_login_attempts` (429): Too many failed sign-in attempts for this email or username from this network. Wait a few minutes and try again.\n- `totp_not_allowed` (401): This account does not accept authenticator apps.\n- `no_usable_factor` (400): The user has no confirmed second factor to challenge.\n- `factor_not_found` (400): No factor with that id belongs to this user.\n- `factor_already_confirmed` (400): The factor was already confirmed.\n- `invalid_factor` (400): The factor cannot be verified (no secret material).\n- `session_missing` (401): The session that started this login no longer exists.\n- `passkey_verification_failed` (400): The WebAuthn response could not be verified.\n- `no_passkey_enrolled` (400): The user has no passkey to sign in with.\n- `malformed_credential` (400): The WebAuthn credential is malformed.\n- `unknown_passkey` (401): The passkey is not enrolled for this user.\n- `invalid_passkey` (401): The passkey assertion did not verify.\n- `invalid_invite_url` (400): An invite's `accept_url` or `redirect_uri` is not an http(s) URL at an origin of this tenant's client callbacks or `callback_hostnames`, or it carries a fragment.\n- `invite_email_mismatch` (403): The invite is for another email address than the accepting user's. `details.invited_email` shows it masked.\n- `invite_email_unverified` (403): The accepting user's email matches the invite but is not verified yet.\n- `invite_not_found` (404): No invite with that id in this account.\n- `invite_used` (400): The invite was already accepted.\n- `already_member` (400): The user is already a member of the team.\n- `not_a_member` (404): The user is not a member of the team.\n- `consent_options_unavailable` (502): The consent screen could not load the choices from the API being authorized (its `consent_options.url`). Try again in a moment.\n- `consent_choice_invalid` (400): The choice sent with the consent decision is not one the API offered for this user.\n- `registration_disabled` (403): Dynamic client registration is turned off for this tenant. Create the client from the dashboard or the Management API, or turn on `dynamic_client_registration_enabled`.\n- `invalid_email_domain` (400): Not an email domain this organization can claim: it must be a plain domain name (`acme.com`), lowercase, without scheme, path or wildcard.\n- `public_email_domain` (400): A public email provider (gmail.com, outlook.com…) cannot belong to an organization: anyone can have an address there.\n- `organization_domain_not_found` (404): The organization has no such domain.\n- `organization_domain_taken` (409): Another organization of this tenant already verified this domain. A domain belongs to one organization.\n- `organization_domain_unverified` (400): The TXT record was not found or does not hold the expected value yet. `details.record` says what was expected and what resolves now; DNS can take a few minutes to propagate.\n- `plan_unavailable` (503): The plan could not be checked right now, and this setting is only for paid plans. Try again in a minute.\n- `organization_domain_mismatch` (403): This organization's identity provider can only sign in addresses of the organization's verified email domains.\n- `team_not_in_organization` (400): Auto-join can only put people in teams of the same organization. `details.teams` lists the others.\n- `organization_has_no_idp` (400): Requiring SSO needs an identity provider: bind an `oidc` connection to the organization first.\n- `organization_not_found` (404): No organization with that id in this account.\n- `invalid_user` (400): The user does not exist in this account.\n- `not_an_organization_admin` (404): The user is not an admin of the organization.\n- `last_organization_admin` (409): An organization keeps at least one admin. Add another admin before removing this one.\n- `team_id_unavailable` (409): The team id cannot be used in this tenant. Pick another id or let the API generate one.\n- `use_team_member_route` (400): This generic route cannot create memberships. Use `POST /team/{team_id}/member` for team members or `POST /role/{role_id}/users` for role grants.\n- `role_not_found` (404): No role with that id in this account.\n- `invalid_role` (400): The role belongs to another account.\n- `invalid_permission` (400): A permission is not in the catalog of its Api, or the Api is not in this account. `details.permissions` lists the ones refused.\n- `flow_not_found` (400): The login flow does not exist in this account.\n- `revision_not_found` (404): The revision is not in the flow history.\n- `invalid_webhook_event` (400): An event is not in the webhook event catalog. `message` and `details.valid_events` list the valid ones.\n- `invalid_webhook_url` (400): The webhook URL must be an absolute `https` URL.\n- `not_a_webhook` (400): The operation only applies to `webhook` subscriptions.\n- `delivery_not_found` (404): No webhook delivery with that id for this subscription.\n- `delivery_in_progress` (409): The delivery is being attempted right now; retry the redeliver in a minute.",
         "enum": [
           "bad_request",
           "validation_error",
@@ -9806,6 +9845,7 @@
           "use_team_member_route",
           "role_not_found",
           "invalid_role",
+          "invalid_permission",
           "flow_not_found",
           "revision_not_found",
           "invalid_webhook_event",
@@ -35630,72 +35670,1631 @@
         }
       }
     },
-    "/role": {
+    "/role/{role_id}/permissions": {
       "get": {
-        "operationId": "role/list",
-        "summary": "List Roles",
+        "operationId": "role/permissions",
+        "summary": "List the permissions of a Role",
         "tags": [
           "role"
         ],
-        "description": "List Roles",
+        "description": "Lists the Api permissions the Role grants, each with its Api. A user gets them in tokens for an Api with `rbac` enabled when the Role is assigned to them at the account level.",
         "parameters": [
           {
             "schema": {
-              "type": "number",
-              "minimum": 1,
-              "maximum": 200
+              "type": "string"
             },
-            "in": "query",
-            "name": "pageSize",
-            "required": false,
-            "description": "Number of items per page (max 200)"
+            "in": "path",
+            "name": "role_id",
+            "required": true
+          }
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Default Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": [
+                      "api",
+                      "api_identifier",
+                      "api_name",
+                      "value"
+                    ],
+                    "properties": {
+                      "api": {
+                        "type": "string",
+                        "description": "Id of the Api that defines it."
+                      },
+                      "api_identifier": {
+                        "type": "string",
+                        "description": "Audience of that Api: the `aud` of the tokens that carry this permission.",
+                        "example": "https://api.example.com"
+                      },
+                      "api_name": {
+                        "type": "string",
+                        "description": "Name of that Api."
+                      },
+                      "value": {
+                        "type": "string",
+                        "description": "The permission, as it appears in the `permissions` claim.",
+                        "example": "invites:write"
+                      },
+                      "description": {
+                        "type": "string",
+                        "description": "The permission's description in the Api."
+                      }
+                    },
+                    "additionalProperties": false,
+                    "description": "A permission granted by a role, joined with its Api. Permissions whose Api was deleted, or that left its catalog, are not listed: they grant nothing."
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "validation_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "`unauthorized` — The request carries no valid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "unauthorized"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "`forbidden` — The credentials are valid but do not allow this operation.\n\n`insufficient_scope` — The token lacks a scope this operation requires. `message` names it.\n\n`user_suspended` — The user is suspended and cannot sign in or be modified.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "forbidden",
+                            "insufficient_scope",
+                            "user_suspended"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "`not_found` — The resource does not exist in this account.\n\n`account_not_found` — No Auth Account matches the request (domain, header or token).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "not_found",
+                            "account_not_found"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "`too_many_requests` — Rate limit exceeded. Honour the `Retry-After` header.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "too_many_requests"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "`internal_error` — Unexpected server error. Retry later; the request id is logged.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "internal_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "role/add_permissions",
+        "summary": "Add permissions to a Role",
+        "tags": [
+          "role"
+        ],
+        "description": "Grants Api permissions to a Role. Each must be in the catalog of an Api of this tenant. Permissions the Role already has are kept. Tokens issued from now on (refreshes included) carry them; tokens already issued are unchanged. Leaves an entry in the tenant's log.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "permissions"
+                ],
+                "properties": {
+                  "permissions": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": [
+                        "api",
+                        "value"
+                      ],
+                      "properties": {
+                        "api": {
+                          "type": "string",
+                          "description": "Id of the Api that defines the permission.",
+                          "example": "api_6555fd293acc2f0fac0e3452"
+                        },
+                        "value": {
+                          "type": "string",
+                          "description": "The permission, as it appears in the Api's `permissions` catalog.",
+                          "example": "invites:write"
+                        }
+                      },
+                      "additionalProperties": false,
+                      "description": "A permission of one Api granted by a role."
+                    },
+                    "minItems": 1,
+                    "description": "Permissions to grant or revoke, each as the Api id plus the value from its catalog.",
+                    "example": [
+                      {
+                        "api": "api_6555fd293acc2f0fac0e3452",
+                        "value": "invites:write"
+                      }
+                    ]
+                  },
+                  "actor_user_id": {
+                    "type": "string",
+                    "description": "The person making the change, when your backend calls on their behalf with a machine token: it is who the tenant's log names. Must be a user of this tenant."
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Permissions to add to or remove from a role."
+              }
+            }
           },
+          "description": "Permissions to add to or remove from a role."
+        },
+        "parameters": [
           {
             "schema": {
               "type": "string"
             },
-            "in": "query",
-            "name": "cursor",
-            "required": false,
-            "description": "Cursor for next page"
+            "in": "path",
+            "name": "role_id",
+            "required": true
+          }
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Default Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": [
+                      "api",
+                      "api_identifier",
+                      "api_name",
+                      "value"
+                    ],
+                    "properties": {
+                      "api": {
+                        "type": "string",
+                        "description": "Id of the Api that defines it."
+                      },
+                      "api_identifier": {
+                        "type": "string",
+                        "description": "Audience of that Api: the `aud` of the tokens that carry this permission.",
+                        "example": "https://api.example.com"
+                      },
+                      "api_name": {
+                        "type": "string",
+                        "description": "Name of that Api."
+                      },
+                      "value": {
+                        "type": "string",
+                        "description": "The permission, as it appears in the `permissions` claim.",
+                        "example": "invites:write"
+                      },
+                      "description": {
+                        "type": "string",
+                        "description": "The permission's description in the Api."
+                      }
+                    },
+                    "additionalProperties": false,
+                    "description": "A permission granted by a role, joined with its Api. Permissions whose Api was deleted, or that left its catalog, are not listed: they grant nothing."
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "`invalid_permission` — A permission is not in the catalog of its Api, or the Api is not in this account. `details.permissions` lists the ones refused.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "invalid_permission",
+                            "validation_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "`unauthorized` — The request carries no valid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "unauthorized"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "`forbidden` — The credentials are valid but do not allow this operation.\n\n`insufficient_scope` — The token lacks a scope this operation requires. `message` names it.\n\n`user_suspended` — The user is suspended and cannot sign in or be modified.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "forbidden",
+                            "insufficient_scope",
+                            "user_suspended"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "`not_found` — The resource does not exist in this account.\n\n`account_not_found` — No Auth Account matches the request (domain, header or token).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "not_found",
+                            "account_not_found"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "`too_many_requests` — Rate limit exceeded. Honour the `Retry-After` header.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "too_many_requests"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "`internal_error` — Unexpected server error. Retry later; the request id is logged.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "internal_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "operationId": "role/remove_permissions",
+        "summary": "Remove permissions from a Role",
+        "tags": [
+          "role"
+        ],
+        "description": "Revokes Api permissions from a Role. Permissions the Role does not have are ignored. Tokens already issued keep them until they expire; refreshes drop them. Leaves an entry in the tenant's log.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "permissions"
+                ],
+                "properties": {
+                  "permissions": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": [
+                        "api",
+                        "value"
+                      ],
+                      "properties": {
+                        "api": {
+                          "type": "string",
+                          "description": "Id of the Api that defines the permission.",
+                          "example": "api_6555fd293acc2f0fac0e3452"
+                        },
+                        "value": {
+                          "type": "string",
+                          "description": "The permission, as it appears in the Api's `permissions` catalog.",
+                          "example": "invites:write"
+                        }
+                      },
+                      "additionalProperties": false,
+                      "description": "A permission of one Api granted by a role."
+                    },
+                    "minItems": 1,
+                    "description": "Permissions to grant or revoke, each as the Api id plus the value from its catalog.",
+                    "example": [
+                      {
+                        "api": "api_6555fd293acc2f0fac0e3452",
+                        "value": "invites:write"
+                      }
+                    ]
+                  },
+                  "actor_user_id": {
+                    "type": "string",
+                    "description": "The person making the change, when your backend calls on their behalf with a machine token: it is who the tenant's log names. Must be a user of this tenant."
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Permissions to add to or remove from a role."
+              }
+            }
           },
+          "description": "Permissions to add to or remove from a role."
+        },
+        "parameters": [
           {
             "schema": {
               "type": "string"
             },
-            "in": "query",
-            "name": "next",
-            "required": false,
-            "description": "Cursor returned by the previous page"
-          },
+            "in": "path",
+            "name": "role_id",
+            "required": true
+          }
+        ],
+        "security": [
           {
-            "schema": {
-              "type": "boolean"
-            },
-            "in": "query",
-            "name": "count",
-            "required": false,
-            "description": "Also return `total`: the rows matching the whole filter, across every page."
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Default Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": [
+                      "api",
+                      "api_identifier",
+                      "api_name",
+                      "value"
+                    ],
+                    "properties": {
+                      "api": {
+                        "type": "string",
+                        "description": "Id of the Api that defines it."
+                      },
+                      "api_identifier": {
+                        "type": "string",
+                        "description": "Audience of that Api: the `aud` of the tokens that carry this permission.",
+                        "example": "https://api.example.com"
+                      },
+                      "api_name": {
+                        "type": "string",
+                        "description": "Name of that Api."
+                      },
+                      "value": {
+                        "type": "string",
+                        "description": "The permission, as it appears in the `permissions` claim.",
+                        "example": "invites:write"
+                      },
+                      "description": {
+                        "type": "string",
+                        "description": "The permission's description in the Api."
+                      }
+                    },
+                    "additionalProperties": false,
+                    "description": "A permission granted by a role, joined with its Api. Permissions whose Api was deleted, or that left its catalog, are not listed: they grant nothing."
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "validation_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "`unauthorized` — The request carries no valid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "unauthorized"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "`forbidden` — The credentials are valid but do not allow this operation.\n\n`insufficient_scope` — The token lacks a scope this operation requires. `message` names it.\n\n`user_suspended` — The user is suspended and cannot sign in or be modified.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "forbidden",
+                            "insufficient_scope",
+                            "user_suspended"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "`not_found` — The resource does not exist in this account.\n\n`account_not_found` — No Auth Account matches the request (domain, header or token).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "not_found",
+                            "account_not_found"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "`too_many_requests` — Rate limit exceeded. Honour the `Retry-After` header.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "too_many_requests"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "`internal_error` — Unexpected server error. Retry later; the request id is logged.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "internal_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/role": {
+      "get": {
+        "operationId": "role/list",
+        "summary": "List Roles",
+        "tags": [
+          "role"
+        ],
+        "description": "List Roles",
+        "parameters": [
+          {
+            "schema": {
+              "type": "number",
+              "minimum": 1,
+              "maximum": 200
+            },
+            "in": "query",
+            "name": "pageSize",
+            "required": false,
+            "description": "Number of items per page (max 200)"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "cursor",
+            "required": false,
+            "description": "Cursor for next page"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "next",
+            "required": false,
+            "description": "Cursor returned by the previous page"
+          },
+          {
+            "schema": {
+              "type": "boolean"
+            },
+            "in": "query",
+            "name": "count",
+            "required": false,
+            "description": "Also return `total`: the rows matching the whole filter, across every page."
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "query",
+            "required": false,
+            "description": "Filter using a FaableQL query"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 200
+            },
+            "in": "query",
+            "name": "q",
+            "required": false,
+            "description": "Full-text search across: `name`, `description`."
+          }
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Default Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "next",
+                    "results"
+                  ],
+                  "properties": {
+                    "next": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Role"
+                      }
+                    },
+                    "total": {
+                      "type": "integer",
+                      "description": "Rows matching the whole filter, across every page. Only with `?count=true`."
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "`invalid_query` — The `?query=` FaableQL expression could not be parsed.\n\n`invalid_expand` — An `?expand=` path is not allowed on this resource.\n\n`search_not_supported` — This resource does not support `?search=`.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "invalid_query",
+                            "invalid_expand",
+                            "search_not_supported",
+                            "validation_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "`unauthorized` — The request carries no valid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "unauthorized"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "`forbidden` — The credentials are valid but do not allow this operation.\n\n`insufficient_scope` — The token lacks a scope this operation requires. `message` names it.\n\n`user_suspended` — The user is suspended and cannot sign in or be modified.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "forbidden",
+                            "insufficient_scope",
+                            "user_suspended"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "`account_not_found` — No Auth Account matches the request (domain, header or token).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "account_not_found"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "`too_many_requests` — Rate limit exceeded. Honour the `Retry-After` header.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "too_many_requests"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "`internal_error` — Unexpected server error. Retry later; the request id is logged.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "internal_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "role/create",
+        "summary": "Create Role",
+        "tags": [
+          "role"
+        ],
+        "description": "Create Role",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "name"
+                ],
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "Short, human-readable identifier for the role (e.g. `admin`, `editor`).",
+                    "example": "admin"
+                  },
+                  "description": {
+                    "type": "string",
+                    "description": "Free-form explanation of what users in this role are expected to do or have access to."
+                  },
+                  "metadata": {
+                    "type": "object",
+                    "properties": {},
+                    "additionalProperties": true,
+                    "description": "Add Metadata"
+                  }
+                },
+                "description": "RoleCreate",
+                "additionalProperties": false
+              }
+            }
+          },
+          "description": "RoleCreate"
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Role",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "id",
+                    "name",
+                    "description",
+                    "permissions",
+                    "account",
+                    "createdAt"
+                  ],
+                  "properties": {
+                    "id": {
+                      "type": "string",
+                      "description": "Role ID"
+                    },
+                    "name": {
+                      "type": "string",
+                      "description": "Short, human-readable identifier for the role (e.g. `admin`, `editor`, `billing-manager`). Surfaced in the dashboard role pickers.",
+                      "example": "admin"
+                    },
+                    "description": {
+                      "type": "string",
+                      "description": "Free-form explanation of what users in this role are expected to do or have access to. Shown alongside the role in the dashboard."
+                    },
+                    "permissions": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "api",
+                          "value"
+                        ],
+                        "properties": {
+                          "api": {
+                            "type": "string",
+                            "description": "Id of the Api that defines the permission.",
+                            "example": "api_6555fd293acc2f0fac0e3452"
+                          },
+                          "value": {
+                            "type": "string",
+                            "description": "The permission, as it appears in the Api's `permissions` catalog.",
+                            "example": "invites:write"
+                          }
+                        },
+                        "additionalProperties": false,
+                        "description": "A permission of one Api granted by a role."
+                      },
+                      "description": "Api permissions granted to the users that hold this role at the account level (team roles grant none). Change them with `POST` / `DELETE /role/:role_id/permissions`; `GET /role/:role_id/permissions` lists them with their Api."
+                    },
+                    "account": {
+                      "type": "string",
+                      "description": "Object is related with this account"
+                    },
+                    "metadata": {
+                      "type": "object",
+                      "properties": {},
+                      "additionalProperties": true,
+                      "description": "RoleMetadata",
+                      "default": {}
+                    },
+                    "createdAt": {
+                      "type": "string",
+                      "description": "Role creation date"
+                    },
+                    "updatedAt": {
+                      "type": "string",
+                      "description": "Role updated date"
+                    }
+                  },
+                  "description": "Role"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "`already_exists` — A resource with the same unique field already exists (for a user, usually `email`). `details.fields` names the field.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "already_exists",
+                            "validation_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "`unauthorized` — The request carries no valid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "unauthorized"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "`forbidden` — The credentials are valid but do not allow this operation.\n\n`insufficient_scope` — The token lacks a scope this operation requires. `message` names it.\n\n`user_suspended` — The user is suspended and cannot sign in or be modified.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "forbidden",
+                            "insufficient_scope",
+                            "user_suspended"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "`account_not_found` — No Auth Account matches the request (domain, header or token).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "account_not_found"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "`too_many_requests` — Rate limit exceeded. Honour the `Retry-After` header.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "too_many_requests"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "`internal_error` — Unexpected server error. Retry later; the request id is logged.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "internal_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/role/{role_id}": {
+      "get": {
+        "operationId": "role/get",
+        "summary": "Get Role",
+        "tags": [
+          "role"
+        ],
+        "description": "Get Role",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "path",
+            "name": "role_id",
+            "required": true
+          }
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Role",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "id",
+                    "name",
+                    "description",
+                    "permissions",
+                    "account",
+                    "createdAt"
+                  ],
+                  "properties": {
+                    "id": {
+                      "type": "string",
+                      "description": "Role ID"
+                    },
+                    "name": {
+                      "type": "string",
+                      "description": "Short, human-readable identifier for the role (e.g. `admin`, `editor`, `billing-manager`). Surfaced in the dashboard role pickers.",
+                      "example": "admin"
+                    },
+                    "description": {
+                      "type": "string",
+                      "description": "Free-form explanation of what users in this role are expected to do or have access to. Shown alongside the role in the dashboard."
+                    },
+                    "permissions": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "api",
+                          "value"
+                        ],
+                        "properties": {
+                          "api": {
+                            "type": "string",
+                            "description": "Id of the Api that defines the permission.",
+                            "example": "api_6555fd293acc2f0fac0e3452"
+                          },
+                          "value": {
+                            "type": "string",
+                            "description": "The permission, as it appears in the Api's `permissions` catalog.",
+                            "example": "invites:write"
+                          }
+                        },
+                        "additionalProperties": false,
+                        "description": "A permission of one Api granted by a role."
+                      },
+                      "description": "Api permissions granted to the users that hold this role at the account level (team roles grant none). Change them with `POST` / `DELETE /role/:role_id/permissions`; `GET /role/:role_id/permissions` lists them with their Api."
+                    },
+                    "account": {
+                      "type": "string",
+                      "description": "Object is related with this account"
+                    },
+                    "metadata": {
+                      "type": "object",
+                      "properties": {},
+                      "additionalProperties": true,
+                      "description": "RoleMetadata",
+                      "default": {}
+                    },
+                    "createdAt": {
+                      "type": "string",
+                      "description": "Role creation date"
+                    },
+                    "updatedAt": {
+                      "type": "string",
+                      "description": "Role updated date"
+                    }
+                  },
+                  "description": "Role"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "`invalid_id` — The id in the path is not a valid id for this resource.\n\n`invalid_expand` — An `?expand=` path is not allowed on this resource.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "invalid_id",
+                            "invalid_expand",
+                            "validation_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "`unauthorized` — The request carries no valid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "unauthorized"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "`forbidden` — The credentials are valid but do not allow this operation.\n\n`insufficient_scope` — The token lacks a scope this operation requires. `message` names it.\n\n`user_suspended` — The user is suspended and cannot sign in or be modified.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "forbidden",
+                            "insufficient_scope",
+                            "user_suspended"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "`not_found` — The resource does not exist in this account.\n\n`account_not_found` — No Auth Account matches the request (domain, header or token).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "not_found",
+                            "account_not_found"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "`too_many_requests` — Rate limit exceeded. Honour the `Retry-After` header.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "too_many_requests"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "`internal_error` — Unexpected server error. Retry later; the request id is logged.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "internal_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "role/update",
+        "summary": "Update Role",
+        "tags": [
+          "role"
+        ],
+        "description": "Update Role",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "New human-readable identifier for the role."
+                  },
+                  "description": {
+                    "type": "string",
+                    "description": "New free-form description of what users in this role do."
+                  }
+                },
+                "description": "Partial update for a Role. Only the supplied fields are modified.",
+                "additionalProperties": false
+              }
+            }
           },
+          "description": "Partial update for a Role. Only the supplied fields are modified."
+        },
+        "parameters": [
           {
             "schema": {
               "type": "string"
             },
-            "in": "query",
-            "name": "query",
-            "required": false,
-            "description": "Filter using a FaableQL query"
-          },
-          {
-            "schema": {
-              "type": "string",
-              "minLength": 1,
-              "maxLength": 200
-            },
-            "in": "query",
-            "name": "q",
-            "required": false,
-            "description": "Full-text search across: `name`, `description`."
+            "in": "path",
+            "name": "role_id",
+            "required": true
           }
         ],
         "security": [
@@ -35705,44 +37304,85 @@
         ],
         "responses": {
           "200": {
-            "description": "Default Response",
+            "description": "Role",
             "content": {
               "application/json": {
                 "schema": {
                   "type": "object",
                   "required": [
-                    "next",
-                    "results"
+                    "id",
+                    "name",
+                    "description",
+                    "permissions",
+                    "account",
+                    "createdAt"
                   ],
                   "properties": {
-                    "next": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ]
+                    "id": {
+                      "type": "string",
+                      "description": "Role ID"
                     },
-                    "results": {
+                    "name": {
+                      "type": "string",
+                      "description": "Short, human-readable identifier for the role (e.g. `admin`, `editor`, `billing-manager`). Surfaced in the dashboard role pickers.",
+                      "example": "admin"
+                    },
+                    "description": {
+                      "type": "string",
+                      "description": "Free-form explanation of what users in this role are expected to do or have access to. Shown alongside the role in the dashboard."
+                    },
+                    "permissions": {
                       "type": "array",
                       "items": {
-                        "$ref": "#/components/schemas/Role"
-                      }
+                        "type": "object",
+                        "required": [
+                          "api",
+                          "value"
+                        ],
+                        "properties": {
+                          "api": {
+                            "type": "string",
+                            "description": "Id of the Api that defines the permission.",
+                            "example": "api_6555fd293acc2f0fac0e3452"
+                          },
+                          "value": {
+                            "type": "string",
+                            "description": "The permission, as it appears in the Api's `permissions` catalog.",
+                            "example": "invites:write"
+                          }
+                        },
+                        "additionalProperties": false,
+                        "description": "A permission of one Api granted by a role."
+                      },
+                      "description": "Api permissions granted to the users that hold this role at the account level (team roles grant none). Change them with `POST` / `DELETE /role/:role_id/permissions`; `GET /role/:role_id/permissions` lists them with their Api."
                     },
-                    "total": {
-                      "type": "integer",
-                      "description": "Rows matching the whole filter, across every page. Only with `?count=true`."
+                    "account": {
+                      "type": "string",
+                      "description": "Object is related with this account"
+                    },
+                    "metadata": {
+                      "type": "object",
+                      "properties": {},
+                      "additionalProperties": true,
+                      "description": "RoleMetadata",
+                      "default": {}
+                    },
+                    "createdAt": {
+                      "type": "string",
+                      "description": "Role creation date"
+                    },
+                    "updatedAt": {
+                      "type": "string",
+                      "description": "Role updated date"
                     }
                   },
-                  "additionalProperties": false
+                  "description": "Role"
                 }
               }
             }
           },
           "400": {
-            "description": "`invalid_query` — The `?query=` FaableQL expression could not be parsed.\n\n`invalid_expand` — An `?expand=` path is not allowed on this resource.\n\n`search_not_supported` — This resource does not support `?search=`.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "description": "`invalid_id` — The id in the path is not a valid id for this resource.\n\n`already_exists` — A resource with the same unique field already exists (for a user, usually `email`). `details.fields` names the field.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
             "content": {
               "application/json": {
                 "schema": {
@@ -35756,9 +37396,8 @@
                         "error_code": {
                           "type": "string",
                           "enum": [
-                            "invalid_query",
-                            "invalid_expand",
-                            "search_not_supported",
+                            "invalid_id",
+                            "already_exists",
                             "validation_error"
                           ]
                         }
@@ -35822,7 +37461,7 @@
             }
           },
           "404": {
-            "description": "`account_not_found` — No Auth Account matches the request (domain, header or token).",
+            "description": "`not_found` — The resource does not exist in this account.\n\n`account_not_found` — No Auth Account matches the request (domain, header or token).",
             "content": {
               "application/json": {
                 "schema": {
@@ -35836,6 +37475,7 @@
                         "error_code": {
                           "type": "string",
                           "enum": [
+                            "not_found",
                             "account_not_found"
                           ]
                         }
@@ -35898,46 +37538,23 @@
           }
         }
       },
-      "post": {
-        "operationId": "role/create",
-        "summary": "Create Role",
+      "delete": {
+        "operationId": "role/delete",
+        "summary": "Delete Role",
         "tags": [
           "role"
         ],
-        "description": "Create Role",
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "required": [
-                  "name"
-                ],
-                "properties": {
-                  "name": {
-                    "type": "string",
-                    "description": "Short, human-readable identifier for the role (e.g. `admin`, `editor`).",
-                    "example": "admin"
-                  },
-                  "description": {
-                    "type": "string",
-                    "description": "Free-form explanation of what users in this role are expected to do or have access to."
-                  },
-                  "metadata": {
-                    "type": "object",
-                    "properties": {},
-                    "additionalProperties": true,
-                    "description": "Add Metadata"
-                  }
-                },
-                "description": "RoleCreate",
-                "additionalProperties": false
-              }
-            }
-          },
-          "description": "RoleCreate"
-        },
+        "description": "Delete Role",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "path",
+            "name": "role_id",
+            "required": true
+          }
+        ],
         "security": [
           {
             "bearerAuth": []
@@ -35954,6 +37571,7 @@
                     "id",
                     "name",
                     "description",
+                    "permissions",
                     "account",
                     "createdAt"
                   ],
@@ -35971,6 +37589,31 @@
                       "type": "string",
                       "description": "Free-form explanation of what users in this role are expected to do or have access to. Shown alongside the role in the dashboard."
                     },
+                    "permissions": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "api",
+                          "value"
+                        ],
+                        "properties": {
+                          "api": {
+                            "type": "string",
+                            "description": "Id of the Api that defines the permission.",
+                            "example": "api_6555fd293acc2f0fac0e3452"
+                          },
+                          "value": {
+                            "type": "string",
+                            "description": "The permission, as it appears in the Api's `permissions` catalog.",
+                            "example": "invites:write"
+                          }
+                        },
+                        "additionalProperties": false,
+                        "description": "A permission of one Api granted by a role."
+                      },
+                      "description": "Api permissions granted to the users that hold this role at the account level (team roles grant none). Change them with `POST` / `DELETE /role/:role_id/permissions`; `GET /role/:role_id/permissions` lists them with their Api."
+                    },
                     "account": {
                       "type": "string",
                       "description": "Object is related with this account"
@@ -35997,7 +37640,7 @@
             }
           },
           "400": {
-            "description": "`already_exists` — A resource with the same unique field already exists (for a user, usually `email`). `details.fields` names the field.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "description": "`invalid_id` — The id in the path is not a valid id for this resource.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
             "content": {
               "application/json": {
                 "schema": {
@@ -36011,7 +37654,7 @@
                         "error_code": {
                           "type": "string",
                           "enum": [
-                            "already_exists",
+                            "invalid_id",
                             "validation_error"
                           ]
                         }
@@ -36075,7 +37718,7 @@
             }
           },
           "404": {
-            "description": "`account_not_found` — No Auth Account matches the request (domain, header or token).",
+            "description": "`not_found` — The resource does not exist in this account.\n\n`account_not_found` — No Auth Account matches the request (domain, header or token).",
             "content": {
               "application/json": {
                 "schema": {
@@ -36089,6 +37732,7 @@
                         "error_code": {
                           "type": "string",
                           "enum": [
+                            "not_found",
                             "account_not_found"
                           ]
                         }
@@ -36152,15 +37796,42 @@
         }
       }
     },
-    "/role/{role_id}": {
+    "/role/{role_id}/users": {
       "get": {
-        "operationId": "role/get",
-        "summary": "Get Role",
+        "operationId": "role/users",
+        "summary": "List Users with Role",
         "tags": [
           "role"
         ],
-        "description": "Get Role",
+        "description": "List Users with Role",
         "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "cursor",
+            "required": false,
+            "description": "Start from this cursor"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "next",
+            "required": false,
+            "description": "Start from this cursor"
+          },
+          {
+            "schema": {
+              "type": "number"
+            },
+            "in": "query",
+            "name": "pageSize",
+            "required": false,
+            "description": "Size of the results array"
+          },
           {
             "schema": {
               "type": "string"
@@ -36177,59 +37848,246 @@
         ],
         "responses": {
           "200": {
-            "description": "Role",
+            "description": "PaginatedResponse",
             "content": {
               "application/json": {
                 "schema": {
                   "type": "object",
                   "required": [
-                    "id",
-                    "name",
-                    "description",
-                    "account",
-                    "createdAt"
+                    "next",
+                    "results"
                   ],
                   "properties": {
-                    "id": {
+                    "next": {
                       "type": "string",
-                      "description": "Role ID"
+                      "description": "next cursor",
+                      "nullable": true
                     },
-                    "name": {
-                      "type": "string",
-                      "description": "Short, human-readable identifier for the role (e.g. `admin`, `editor`, `billing-manager`). Surfaced in the dashboard role pickers.",
-                      "example": "admin"
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/RoleMember"
+                      },
+                      "description": "List of results"
+                    }
+                  },
+                  "description": "PaginatedResponse",
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
                     },
-                    "description": {
-                      "type": "string",
-                      "description": "Free-form explanation of what users in this role are expected to do or have access to. Shown alongside the role in the dashboard."
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "validation_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "`unauthorized` — The request carries no valid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
                     },
-                    "account": {
-                      "type": "string",
-                      "description": "Object is related with this account"
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "unauthorized"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "`forbidden` — The credentials are valid but do not allow this operation.\n\n`insufficient_scope` — The token lacks a scope this operation requires. `message` names it.\n\n`user_suspended` — The user is suspended and cannot sign in or be modified.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
                     },
-                    "metadata": {
+                    {
                       "type": "object",
-                      "properties": {},
-                      "additionalProperties": true,
-                      "description": "RoleMetadata",
-                      "default": {}
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "forbidden",
+                            "insufficient_scope",
+                            "user_suspended"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "`role_not_found` — No role with that id in this account.\n\n`account_not_found` — No Auth Account matches the request (domain, header or token).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
                     },
-                    "createdAt": {
-                      "type": "string",
-                      "description": "Role creation date"
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "role_not_found",
+                            "account_not_found"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "`too_many_requests` — Rate limit exceeded. Honour the `Retry-After` header.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
                     },
-                    "updatedAt": {
-                      "type": "string",
-                      "description": "Role updated date"
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "too_many_requests"
+                          ]
+                        }
+                      }
                     }
-                  },
-                  "description": "Role"
+                  ]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "`internal_error` — Unexpected server error. Retry later; the request id is logged.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "internal_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
                 }
               }
             }
+          }
+        }
+      },
+      "post": {
+        "operationId": "role/assign_users",
+        "summary": "Assign Users to Role",
+        "tags": [
+          "role"
+        ],
+        "description": "Assign Users to Role",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "users"
+                ],
+                "properties": {
+                  "users": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "List of User ids to grant the role to. Existing role memberships are preserved; passing a user that already holds the role is a no-op.",
+                    "example": [
+                      "user_6555fd293acc2f0fac0e3452"
+                    ]
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Payload for granting a role to one or more users in a single call. Posted to `POST /role/:role_id/users`."
+              }
+            }
+          },
+          "description": "Payload for granting a role to one or more users in a single call. Posted to `POST /role/:role_id/users`."
+        },
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "path",
+            "name": "role_id",
+            "required": true
+          }
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Default Response"
           },
           "400": {
-            "description": "`invalid_id` — The id in the path is not a valid id for this resource.\n\n`invalid_expand` — An `?expand=` path is not allowed on this resource.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "description": "`invalid_role` — The role belongs to another account.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
             "content": {
               "application/json": {
                 "schema": {
@@ -36243,8 +38101,7 @@
                         "error_code": {
                           "type": "string",
                           "enum": [
-                            "invalid_id",
-                            "invalid_expand",
+                            "invalid_role",
                             "validation_error"
                           ]
                         }
@@ -36308,7 +38165,7 @@
             }
           },
           "404": {
-            "description": "`not_found` — The resource does not exist in this account.\n\n`account_not_found` — No Auth Account matches the request (domain, header or token).",
+            "description": "`role_not_found` — No role with that id in this account.\n\n`account_not_found` — No Auth Account matches the request (domain, header or token).",
             "content": {
               "application/json": {
                 "schema": {
@@ -36322,7 +38179,7 @@
                         "error_code": {
                           "type": "string",
                           "enum": [
-                            "not_found",
+                            "role_not_found",
                             "account_not_found"
                           ]
                         }
@@ -36385,35 +38242,41 @@
           }
         }
       },
-      "post": {
-        "operationId": "role/update",
-        "summary": "Update Role",
+      "delete": {
+        "operationId": "role/remove_users",
+        "summary": "Remove Users from Role",
         "tags": [
           "role"
         ],
-        "description": "Update Role",
+        "description": "Revokes an account-level role from users. Their next tokens (refreshes included) no longer carry its permissions; tokens already issued keep them until they expire. Leaves an entry in the tenant's log.",
         "requestBody": {
           "required": true,
           "content": {
             "application/json": {
               "schema": {
                 "type": "object",
+                "required": [
+                  "users"
+                ],
                 "properties": {
-                  "name": {
-                    "type": "string",
-                    "description": "New human-readable identifier for the role."
-                  },
-                  "description": {
-                    "type": "string",
-                    "description": "New free-form description of what users in this role do."
+                  "users": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "minItems": 1,
+                    "description": "User ids to revoke the role from. A user that does not hold it is reported in `not_in_role`, not an error.",
+                    "example": [
+                      "user_6555fd293acc2f0fac0e3452"
+                    ]
                   }
                 },
-                "description": "Partial update for a Role. Only the supplied fields are modified.",
-                "additionalProperties": false
+                "additionalProperties": false,
+                "description": "Payload for revoking a role from one or more users. Sent to `DELETE /role/:role_id/users`."
               }
             }
           },
-          "description": "Partial update for a Role. Only the supplied fields are modified."
+          "description": "Payload for revoking a role from one or more users. Sent to `DELETE /role/:role_id/users`."
         },
         "parameters": [
           {
@@ -36432,59 +38295,36 @@
         ],
         "responses": {
           "200": {
-            "description": "Role",
+            "description": "Default Response",
             "content": {
               "application/json": {
                 "schema": {
                   "type": "object",
                   "required": [
-                    "id",
-                    "name",
-                    "description",
-                    "account",
-                    "createdAt"
+                    "removed_from_role",
+                    "not_in_role"
                   ],
                   "properties": {
-                    "id": {
-                      "type": "string",
-                      "description": "Role ID"
-                    },
-                    "name": {
-                      "type": "string",
-                      "description": "Short, human-readable identifier for the role (e.g. `admin`, `editor`, `billing-manager`). Surfaced in the dashboard role pickers.",
-                      "example": "admin"
-                    },
-                    "description": {
-                      "type": "string",
-                      "description": "Free-form explanation of what users in this role are expected to do or have access to. Shown alongside the role in the dashboard."
-                    },
-                    "account": {
-                      "type": "string",
-                      "description": "Object is related with this account"
-                    },
-                    "metadata": {
-                      "type": "object",
-                      "properties": {},
-                      "additionalProperties": true,
-                      "description": "RoleMetadata",
-                      "default": {}
-                    },
-                    "createdAt": {
-                      "type": "string",
-                      "description": "Role creation date"
+                    "removed_from_role": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
                     },
-                    "updatedAt": {
-                      "type": "string",
-                      "description": "Role updated date"
+                    "not_in_role": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
                     }
                   },
-                  "description": "Role"
+                  "additionalProperties": false
                 }
               }
             }
           },
           "400": {
-            "description": "`invalid_id` — The id in the path is not a valid id for this resource.\n\n`already_exists` — A resource with the same unique field already exists (for a user, usually `email`). `details.fields` names the field.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "description": "`invalid_role` — The role belongs to another account.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
             "content": {
               "application/json": {
                 "schema": {
@@ -36498,8 +38338,7 @@
                         "error_code": {
                           "type": "string",
                           "enum": [
-                            "invalid_id",
-                            "already_exists",
+                            "invalid_role",
                             "validation_error"
                           ]
                         }
@@ -36639,21 +38478,23 @@
             }
           }
         }
-      },
-      "delete": {
-        "operationId": "role/delete",
-        "summary": "Delete Role",
+      }
+    },
+    "/user/{user_id}/roles": {
+      "get": {
+        "operationId": "user/roles",
+        "summary": "List a User's roles",
         "tags": [
-          "role"
+          "user"
         ],
-        "description": "Delete Role",
+        "description": "Lists the roles assigned to the User at the account level, by name. Account-level roles are what grant Api permissions to a user (in tokens for an Api with `rbac` enabled). Team roles are separate: they live on the team membership and grant no permissions.",
         "parameters": [
           {
             "schema": {
               "type": "string"
             },
             "in": "path",
-            "name": "role_id",
+            "name": "user_id",
             "required": true
           }
         ],
@@ -36664,59 +38505,88 @@
         ],
         "responses": {
           "200": {
-            "description": "Role",
+            "description": "Default Response",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "required": [
-                    "id",
-                    "name",
-                    "description",
-                    "account",
-                    "createdAt"
-                  ],
-                  "properties": {
-                    "id": {
-                      "type": "string",
-                      "description": "Role ID"
-                    },
-                    "name": {
-                      "type": "string",
-                      "description": "Short, human-readable identifier for the role (e.g. `admin`, `editor`, `billing-manager`). Surfaced in the dashboard role pickers.",
-                      "example": "admin"
-                    },
-                    "description": {
-                      "type": "string",
-                      "description": "Free-form explanation of what users in this role are expected to do or have access to. Shown alongside the role in the dashboard."
-                    },
-                    "account": {
-                      "type": "string",
-                      "description": "Object is related with this account"
-                    },
-                    "metadata": {
-                      "type": "object",
-                      "properties": {},
-                      "additionalProperties": true,
-                      "description": "RoleMetadata",
-                      "default": {}
-                    },
-                    "createdAt": {
-                      "type": "string",
-                      "description": "Role creation date"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": [
+                      "id",
+                      "name",
+                      "description",
+                      "permissions",
+                      "account",
+                      "createdAt"
+                    ],
+                    "properties": {
+                      "id": {
+                        "type": "string",
+                        "description": "Role ID"
+                      },
+                      "name": {
+                        "type": "string",
+                        "description": "Short, human-readable identifier for the role (e.g. `admin`, `editor`, `billing-manager`). Surfaced in the dashboard role pickers.",
+                        "example": "admin"
+                      },
+                      "description": {
+                        "type": "string",
+                        "description": "Free-form explanation of what users in this role are expected to do or have access to. Shown alongside the role in the dashboard."
+                      },
+                      "permissions": {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "required": [
+                            "api",
+                            "value"
+                          ],
+                          "properties": {
+                            "api": {
+                              "type": "string",
+                              "description": "Id of the Api that defines the permission.",
+                              "example": "api_6555fd293acc2f0fac0e3452"
+                            },
+                            "value": {
+                              "type": "string",
+                              "description": "The permission, as it appears in the Api's `permissions` catalog.",
+                              "example": "invites:write"
+                            }
+                          },
+                          "additionalProperties": false,
+                          "description": "A permission of one Api granted by a role."
+                        },
+                        "description": "Api permissions granted to the users that hold this role at the account level (team roles grant none). Change them with `POST` / `DELETE /role/:role_id/permissions`; `GET /role/:role_id/permissions` lists them with their Api."
+                      },
+                      "account": {
+                        "type": "string",
+                        "description": "Object is related with this account"
+                      },
+                      "metadata": {
+                        "type": "object",
+                        "properties": {},
+                        "additionalProperties": true,
+                        "description": "RoleMetadata",
+                        "default": {}
+                      },
+                      "createdAt": {
+                        "type": "string",
+                        "description": "Role creation date"
+                      },
+                      "updatedAt": {
+                        "type": "string",
+                        "description": "Role updated date"
+                      }
                     },
-                    "updatedAt": {
-                      "type": "string",
-                      "description": "Role updated date"
-                    }
-                  },
-                  "description": "Role"
+                    "description": "Role"
+                  }
                 }
               }
             }
           },
           "400": {
-            "description": "`invalid_id` — The id in the path is not a valid id for this resource.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "description": "`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
             "content": {
               "application/json": {
                 "schema": {
@@ -36730,7 +38600,6 @@
                         "error_code": {
                           "type": "string",
                           "enum": [
-                            "invalid_id",
                             "validation_error"
                           ]
                         }
@@ -36870,50 +38739,54 @@
             }
           }
         }
-      }
-    },
-    "/role/{role_id}/users": {
-      "get": {
-        "operationId": "role/users",
-        "summary": "List Users with Role",
+      },
+      "post": {
+        "operationId": "user/assign_roles",
+        "summary": "Assign roles to a User",
         "tags": [
-          "role"
+          "user"
         ],
-        "description": "List Users with Role",
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "in": "query",
-            "name": "cursor",
-            "required": false,
-            "description": "Start from this cursor"
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "in": "query",
-            "name": "next",
-            "required": false,
-            "description": "Start from this cursor"
-          },
-          {
-            "schema": {
-              "type": "number"
-            },
-            "in": "query",
-            "name": "pageSize",
-            "required": false,
-            "description": "Size of the results array"
+        "description": "Assigns account-level roles to the User and returns all of their roles. Roles the User already has are kept. Their next tokens (refreshes included) carry the new permissions. Leaves an entry in the tenant's log. Account-level roles are what grant Api permissions to a user (in tokens for an Api with `rbac` enabled). Team roles are separate: they live on the team membership and grant no permissions.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "roles"
+                ],
+                "properties": {
+                  "roles": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "minItems": 1,
+                    "description": "Role ids of this tenant.",
+                    "example": [
+                      "role_6555fd293acc2f0fac0e3452"
+                    ]
+                  },
+                  "actor_user_id": {
+                    "type": "string",
+                    "description": "The person making the change, when your backend calls on their behalf with a machine token: it is who the tenant's log names. Must be a user of this tenant."
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Account-level roles to assign to or remove from a user."
+              }
+            }
           },
+          "description": "Account-level roles to assign to or remove from a user."
+        },
+        "parameters": [
           {
             "schema": {
               "type": "string"
             },
             "in": "path",
-            "name": "role_id",
+            "name": "user_id",
             "required": true
           }
         ],
@@ -36924,37 +38797,88 @@
         ],
         "responses": {
           "200": {
-            "description": "PaginatedResponse",
+            "description": "Default Response",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "required": [
-                    "next",
-                    "results"
-                  ],
-                  "properties": {
-                    "next": {
-                      "type": "string",
-                      "description": "next cursor",
-                      "nullable": true
-                    },
-                    "results": {
-                      "type": "array",
-                      "items": {
-                        "$ref": "#/components/schemas/RoleMember"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": [
+                      "id",
+                      "name",
+                      "description",
+                      "permissions",
+                      "account",
+                      "createdAt"
+                    ],
+                    "properties": {
+                      "id": {
+                        "type": "string",
+                        "description": "Role ID"
                       },
-                      "description": "List of results"
-                    }
-                  },
-                  "description": "PaginatedResponse",
-                  "additionalProperties": false
+                      "name": {
+                        "type": "string",
+                        "description": "Short, human-readable identifier for the role (e.g. `admin`, `editor`, `billing-manager`). Surfaced in the dashboard role pickers.",
+                        "example": "admin"
+                      },
+                      "description": {
+                        "type": "string",
+                        "description": "Free-form explanation of what users in this role are expected to do or have access to. Shown alongside the role in the dashboard."
+                      },
+                      "permissions": {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "required": [
+                            "api",
+                            "value"
+                          ],
+                          "properties": {
+                            "api": {
+                              "type": "string",
+                              "description": "Id of the Api that defines the permission.",
+                              "example": "api_6555fd293acc2f0fac0e3452"
+                            },
+                            "value": {
+                              "type": "string",
+                              "description": "The permission, as it appears in the Api's `permissions` catalog.",
+                              "example": "invites:write"
+                            }
+                          },
+                          "additionalProperties": false,
+                          "description": "A permission of one Api granted by a role."
+                        },
+                        "description": "Api permissions granted to the users that hold this role at the account level (team roles grant none). Change them with `POST` / `DELETE /role/:role_id/permissions`; `GET /role/:role_id/permissions` lists them with their Api."
+                      },
+                      "account": {
+                        "type": "string",
+                        "description": "Object is related with this account"
+                      },
+                      "metadata": {
+                        "type": "object",
+                        "properties": {},
+                        "additionalProperties": true,
+                        "description": "RoleMetadata",
+                        "default": {}
+                      },
+                      "createdAt": {
+                        "type": "string",
+                        "description": "Role creation date"
+                      },
+                      "updatedAt": {
+                        "type": "string",
+                        "description": "Role updated date"
+                      }
+                    },
+                    "description": "Role"
+                  }
                 }
               }
             }
           },
           "400": {
-            "description": "`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "description": "`invalid_role` — The role belongs to another account.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
             "content": {
               "application/json": {
                 "schema": {
@@ -36968,6 +38892,7 @@
                         "error_code": {
                           "type": "string",
                           "enum": [
+                            "invalid_role",
                             "validation_error"
                           ]
                         }
@@ -37031,7 +38956,7 @@
             }
           },
           "404": {
-            "description": "`role_not_found` — No role with that id in this account.\n\n`account_not_found` — No Auth Account matches the request (domain, header or token).",
+            "description": "`not_found` — The resource does not exist in this account.\n\n`account_not_found` — No Auth Account matches the request (domain, header or token).",
             "content": {
               "application/json": {
                 "schema": {
@@ -37045,7 +38970,7 @@
                         "error_code": {
                           "type": "string",
                           "enum": [
-                            "role_not_found",
+                            "not_found",
                             "account_not_found"
                           ]
                         }
@@ -37108,13 +39033,13 @@
           }
         }
       },
-      "post": {
-        "operationId": "role/assign_users",
-        "summary": "Assign Users to Role",
+      "delete": {
+        "operationId": "user/remove_roles",
+        "summary": "Remove roles from a User",
         "tags": [
-          "role"
+          "user"
         ],
-        "description": "Assign Users to Role",
+        "description": "Removes account-level roles from the User and returns the ones left. Roles the User does not have are ignored. Tokens already issued keep the permissions until they expire; refreshes drop them. Leaves an entry in the tenant's log.",
         "requestBody": {
           "required": true,
           "content": {
@@ -37122,26 +39047,31 @@
               "schema": {
                 "type": "object",
                 "required": [
-                  "users"
+                  "roles"
                 ],
                 "properties": {
-                  "users": {
+                  "roles": {
                     "type": "array",
                     "items": {
                       "type": "string"
                     },
-                    "description": "List of User ids to grant the role to. Existing role memberships are preserved; passing a user that already holds the role is a no-op.",
+                    "minItems": 1,
+                    "description": "Role ids of this tenant.",
                     "example": [
-                      "user_6555fd293acc2f0fac0e3452"
+                      "role_6555fd293acc2f0fac0e3452"
                     ]
+                  },
+                  "actor_user_id": {
+                    "type": "string",
+                    "description": "The person making the change, when your backend calls on their behalf with a machine token: it is who the tenant's log names. Must be a user of this tenant."
                   }
                 },
                 "additionalProperties": false,
-                "description": "Payload for granting a role to one or more users in a single call. Posted to `POST /role/:role_id/users`."
+                "description": "Account-level roles to assign to or remove from a user."
               }
             }
           },
-          "description": "Payload for granting a role to one or more users in a single call. Posted to `POST /role/:role_id/users`."
+          "description": "Account-level roles to assign to or remove from a user."
         },
         "parameters": [
           {
@@ -37149,7 +39079,7 @@
               "type": "string"
             },
             "in": "path",
-            "name": "role_id",
+            "name": "user_id",
             "required": true
           }
         ],
@@ -37160,10 +39090,88 @@
         ],
         "responses": {
           "200": {
-            "description": "Default Response"
+            "description": "Default Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": [
+                      "id",
+                      "name",
+                      "description",
+                      "permissions",
+                      "account",
+                      "createdAt"
+                    ],
+                    "properties": {
+                      "id": {
+                        "type": "string",
+                        "description": "Role ID"
+                      },
+                      "name": {
+                        "type": "string",
+                        "description": "Short, human-readable identifier for the role (e.g. `admin`, `editor`, `billing-manager`). Surfaced in the dashboard role pickers.",
+                        "example": "admin"
+                      },
+                      "description": {
+                        "type": "string",
+                        "description": "Free-form explanation of what users in this role are expected to do or have access to. Shown alongside the role in the dashboard."
+                      },
+                      "permissions": {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "required": [
+                            "api",
+                            "value"
+                          ],
+                          "properties": {
+                            "api": {
+                              "type": "string",
+                              "description": "Id of the Api that defines the permission.",
+                              "example": "api_6555fd293acc2f0fac0e3452"
+                            },
+                            "value": {
+                              "type": "string",
+                              "description": "The permission, as it appears in the Api's `permissions` catalog.",
+                              "example": "invites:write"
+                            }
+                          },
+                          "additionalProperties": false,
+                          "description": "A permission of one Api granted by a role."
+                        },
+                        "description": "Api permissions granted to the users that hold this role at the account level (team roles grant none). Change them with `POST` / `DELETE /role/:role_id/permissions`; `GET /role/:role_id/permissions` lists them with their Api."
+                      },
+                      "account": {
+                        "type": "string",
+                        "description": "Object is related with this account"
+                      },
+                      "metadata": {
+                        "type": "object",
+                        "properties": {},
+                        "additionalProperties": true,
+                        "description": "RoleMetadata",
+                        "default": {}
+                      },
+                      "createdAt": {
+                        "type": "string",
+                        "description": "Role creation date"
+                      },
+                      "updatedAt": {
+                        "type": "string",
+                        "description": "Role updated date"
+                      }
+                    },
+                    "description": "Role"
+                  }
+                }
+              }
+            }
           },
           "400": {
-            "description": "`invalid_role` — The role belongs to another account.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "description": "`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
             "content": {
               "application/json": {
                 "schema": {
@@ -37177,7 +39185,6 @@
                         "error_code": {
                           "type": "string",
                           "enum": [
-                            "invalid_role",
                             "validation_error"
                           ]
                         }
@@ -37241,7 +39248,7 @@
             }
           },
           "404": {
-            "description": "`role_not_found` — No role with that id in this account.\n\n`account_not_found` — No Auth Account matches the request (domain, header or token).",
+            "description": "`not_found` — The resource does not exist in this account.\n\n`account_not_found` — No Auth Account matches the request (domain, header or token).",
             "content": {
               "application/json": {
                 "schema": {
@@ -37255,7 +39262,253 @@
                         "error_code": {
                           "type": "string",
                           "enum": [
-                            "role_not_found",
+                            "not_found",
+                            "account_not_found"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "`too_many_requests` — Rate limit exceeded. Honour the `Retry-After` header.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "too_many_requests"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "`internal_error` — Unexpected server error. Retry later; the request id is logged.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "internal_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/user/{user_id}/permissions": {
+      "get": {
+        "operationId": "user/permissions",
+        "summary": "List a User's permissions",
+        "tags": [
+          "user"
+        ],
+        "description": "Lists the Api permissions the User holds through their account-level roles, with the roles that grant each one. For an Api with `rbac` enabled, these are exactly what the User's tokens for that Api carry in `permissions`.",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "path",
+            "name": "user_id",
+            "required": true
+          }
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Default Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": [
+                      "api",
+                      "api_identifier",
+                      "api_name",
+                      "value",
+                      "roles"
+                    ],
+                    "properties": {
+                      "api": {
+                        "type": "string",
+                        "description": "Id of the Api that defines it."
+                      },
+                      "api_identifier": {
+                        "type": "string",
+                        "description": "Audience of that Api: the `aud` of the tokens that carry this permission.",
+                        "example": "https://api.example.com"
+                      },
+                      "api_name": {
+                        "type": "string",
+                        "description": "Name of that Api."
+                      },
+                      "value": {
+                        "type": "string",
+                        "description": "The permission, as it appears in the `permissions` claim.",
+                        "example": "invites:write"
+                      },
+                      "description": {
+                        "type": "string",
+                        "description": "The permission's description in the Api."
+                      },
+                      "roles": {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "required": [
+                            "id",
+                            "name"
+                          ],
+                          "properties": {
+                            "id": {
+                              "type": "string"
+                            },
+                            "name": {
+                              "type": "string"
+                            }
+                          },
+                          "additionalProperties": false
+                        },
+                        "description": "The roles of the user that grant it."
+                      }
+                    },
+                    "additionalProperties": false,
+                    "description": "A permission the user holds through their account-level roles, with the roles that grant it."
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "validation_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "`unauthorized` — The request carries no valid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "unauthorized"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "`forbidden` — The credentials are valid but do not allow this operation.\n\n`insufficient_scope` — The token lacks a scope this operation requires. `message` names it.\n\n`user_suspended` — The user is suspended and cannot sign in or be modified.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "forbidden",
+                            "insufficient_scope",
+                            "user_suspended"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "`not_found` — The resource does not exist in this account.\n\n`account_not_found` — No Auth Account matches the request (domain, header or token).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "not_found",
                             "account_not_found"
                           ]
                         }
@@ -48319,6 +50572,15 @@
             "required": false,
             "description": "Exact match on `enforce_policies`. Equivalent to `?query=enforce_policies:<value>`."
           },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "rbac",
+            "required": false,
+            "description": "Exact match on `rbac`. Equivalent to `?query=rbac:<value>`."
+          },
           {
             "schema": {
               "type": "string"
@@ -48636,6 +50898,10 @@
                     "type": "boolean",
                     "description": "When true, requested scopes are filtered against `permissions` at token issuance."
                   },
+                  "rbac": {
+                    "type": "boolean",
+                    "description": "When true, user tokens carry only the permissions granted to the user's roles. Defaults to false."
+                  },
                   "allow_offline_access": {
                     "type": "boolean",
                     "description": "When true, clients can request `offline_access` and receive a refresh_token for this API."
@@ -48741,6 +51007,7 @@
                     "token_dialect",
                     "token_lifetime",
                     "enforce_policies",
+                    "rbac",
                     "allow_offline_access",
                     "skip_consent",
                     "include_teams_in_access_token",
@@ -48818,6 +51085,10 @@
                       "type": "boolean",
                       "description": "When true, only scopes that match a permission in `permissions` are forwarded into the access_token. When false, requested scopes are echoed back verbatim with no filtering."
                     },
+                    "rbac": {
+                      "type": "boolean",
+                      "description": "Role-based access control. When true, a token issued to a user carries only the permissions of this API granted to the user's roles (account-level role assignments, not team roles): `permissions` lists all of them, and `scope` keeps only the requested ones the user holds. Machine-to-machine tokens (`client_credentials`) are not affected. The `permissions` claim requires `token_dialect: access_token_authz`."
+                    },
                     "allow_offline_access": {
                       "type": "boolean",
                       "description": "When true, the API is eligible to be the target of a `refresh_token` (i.e. clients can request `offline_access` against it)."
@@ -49116,6 +51387,7 @@
                     "token_dialect",
                     "token_lifetime",
                     "enforce_policies",
+                    "rbac",
                     "allow_offline_access",
                     "skip_consent",
                     "include_teams_in_access_token",
@@ -49193,6 +51465,10 @@
                       "type": "boolean",
                       "description": "When true, only scopes that match a permission in `permissions` are forwarded into the access_token. When false, requested scopes are echoed back verbatim with no filtering."
                     },
+                    "rbac": {
+                      "type": "boolean",
+                      "description": "Role-based access control. When true, a token issued to a user carries only the permissions of this API granted to the user's roles (account-level role assignments, not team roles): `permissions` lists all of them, and `scope` keeps only the requested ones the user holds. Machine-to-machine tokens (`client_credentials`) are not affected. The `permissions` claim requires `token_dialect: access_token_authz`."
+                    },
                     "allow_offline_access": {
                       "type": "boolean",
                       "description": "When true, the API is eligible to be the target of a `refresh_token` (i.e. clients can request `offline_access` against it)."
@@ -49519,6 +51795,10 @@
                     "type": "boolean",
                     "description": "When true, requested scopes are filtered against `permissions` at token issuance."
                   },
+                  "rbac": {
+                    "type": "boolean",
+                    "description": "When true, user tokens carry only the permissions granted to the user's roles. Applies to tokens issued after the update, including refreshes."
+                  },
                   "allow_offline_access": {
                     "type": "boolean",
                     "description": "When true, clients can request `offline_access` and receive a refresh_token for this API."
@@ -49636,6 +51916,7 @@
                     "token_dialect",
                     "token_lifetime",
                     "enforce_policies",
+                    "rbac",
                     "allow_offline_access",
                     "skip_consent",
                     "include_teams_in_access_token",
@@ -49713,6 +51994,10 @@
                       "type": "boolean",
                       "description": "When true, only scopes that match a permission in `permissions` are forwarded into the access_token. When false, requested scopes are echoed back verbatim with no filtering."
                     },
+                    "rbac": {
+                      "type": "boolean",
+                      "description": "Role-based access control. When true, a token issued to a user carries only the permissions of this API granted to the user's roles (account-level role assignments, not team roles): `permissions` lists all of them, and `scope` keeps only the requested ones the user holds. Machine-to-machine tokens (`client_credentials`) are not affected. The `permissions` claim requires `token_dialect: access_token_authz`."
+                    },
                     "allow_offline_access": {
                       "type": "boolean",
                       "description": "When true, the API is eligible to be the target of a `refresh_token` (i.e. clients can request `offline_access` against it)."
@@ -50011,6 +52296,7 @@
                     "token_dialect",
                     "token_lifetime",
                     "enforce_policies",
+                    "rbac",
                     "allow_offline_access",
                     "skip_consent",
                     "include_teams_in_access_token",
@@ -50088,6 +52374,10 @@
                       "type": "boolean",
                       "description": "When true, only scopes that match a permission in `permissions` are forwarded into the access_token. When false, requested scopes are echoed back verbatim with no filtering."
                     },
+                    "rbac": {
+                      "type": "boolean",
+                      "description": "Role-based access control. When true, a token issued to a user carries only the permissions of this API granted to the user's roles (account-level role assignments, not team roles): `permissions` lists all of them, and `scope` keeps only the requested ones the user holds. Machine-to-machine tokens (`client_credentials`) are not affected. The `permissions` claim requires `token_dialect: access_token_authz`."
+                    },
                     "allow_offline_access": {
                       "type": "boolean",
                       "description": "When true, the API is eligible to be the target of a `refresh_token` (i.e. clients can request `offline_access` against it)."
@@ -79381,11 +81671,11 @@
     },
     {
       "name": "role",
-      "description": "Account-wide roles. A Role is a named label (e.g. `admin`, `editor`) that can be granted to users via RoleMember. Roles are the primary RBAC primitive used by downstream services to gate access."
+      "description": "Account-wide roles. A Role has a name (e.g. `admin`, `editor`) and a set of Api permissions. Assigned to a user at the account level (`POST /role/:role_id/users` or `POST /user/:user_id/roles`), it puts those permissions in the user's tokens for every Api with `rbac` enabled. The same Roles can be held inside a Team, where they are names only (the `roles` claim) and grant no permissions."
     },
     {
       "name": "rolemember",
-      "description": "Grants of a Role to a User at the account level. Each RoleMember binds one (role, user) pair. Use `GET /role/:role_id/users` to list everyone holding a given role, and `POST /role/:role_id/users` to grant a role to one or more users in bulk."
+      "description": "Grants of a Role to a User at the account level: what gives a user Api permissions. Each RoleMember binds one (role, user) pair. From the role side, `GET`, `POST` and `DELETE /role/:role_id/users`; from the user side, `GET`, `POST` and `DELETE /user/:user_id/roles`, and `GET /user/:user_id/permissions` for the resulting permissions."
     },
     {
       "name": "team",