@productcraft/platform-auth 0.2.0 → 1.0.0

package/api.md

@@ -0,0 +1,1716 @@
+# @productcraft/platform-auth API reference
+
+<!-- Generated by scripts/gen-sdk.mjs from Specs/platform-auth.json. Do not edit. -->
+<!-- snippet-preamble: import { PlatformAuth } from "@productcraft/platform-auth"; const platform = new PlatformAuth(); -->
+
+Every method of `PlatformAuth`, grouped by resource. Types are under the `PlatformAuth` namespace (`import type { PlatformAuth } from "@productcraft/platform-auth"`). Every method takes per-request options last (`{ idempotencyKey, timeout, maxRetries, headers, signal, workspaceId }`).
+
+## account
+
+### `platform.account.erase(options?)`
+
+`DELETE /v1/account` → `void`
+
+Delete the calling account. Auto-promotes the oldest admin (or oldest non-self member) to owner in any workspace where the departing account is the sole owner. Linked provider grants that require server-side revocation (Sign in with Apple) are revoked with the provider.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, invalid or expired bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The session lacks the required action for self-account deletion (defence-in-depth — the route is guarded but the cookie may be present without action access). |
+| 404 | `NotFoundError` | `NOT_FOUND` | No account row exists for the session principal. Should never fire for a valid session — surfaced for SDKs. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.account.erase();
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#delete-v1-account)
+
+## apiKeys
+
+### `platform.apiKeys.self(options?)`
+
+`GET /v1/api-keys/self` → `PlatformAuth.ApiKeySelf`
+
+Describe the workspace key making this request: its name, workspace, expiry and what it may do in plain sentences. Call it with `Authorization: Bearer pcft_live_…` to test a key right after minting it.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | No bearer, or the key is unknown, revoked or expired. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `WORKSPACE_KEY_REQUIRED` | Signed in with a session or another token instead of a workspace key (`WORKSPACE_KEY_REQUIRED`). Send the `pcft_live_…` key as the bearer. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `PAK_NOT_FOUND` | The key was deleted while the request was in flight (`PAK_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const apiKeySelf = await platform.apiKeys.self();
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-api-keys-self)
+
+## auth
+
+### `platform.auth.logout(params, options?)`
+
+`POST /v1/auth/logout` → `void`
+
+Logout by revoking refresh token.
+
+- Params: `PlatformAuth.AuthLogoutParams`
+- Public: no API key, browser-safe
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failed or invalid token |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.auth.logout({ refresh_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-auth-logout)
+
+### `platform.auth.logoutCurrent(options?)`
+
+`POST /v1/auth/logout-current` → `void`
+
+Revoke the server-side session tied to the caller’s current access token.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid access token |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.auth.logoutCurrent();
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-auth-logout-current)
+
+### `platform.auth.refresh(params, options?)`
+
+`POST /v1/auth/refresh` → `PlatformAuth.Token`
+
+Refresh access token using refresh token.
+
+- Params: `PlatformAuth.AuthRefreshParams`
+- Public: no API key, browser-safe
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failed or invalid token |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const token = await platform.auth.refresh({ refresh_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-auth-refresh)
+
+### `platform.auth.signin(params, options?)`
+
+`POST /v1/auth/signin` → `PlatformAuth.Token`
+
+Sign in with email/username and password.
+
+Every failed attempt answers `401 INVALID_CREDENTIALS`, whatever went wrong: unknown identifier, wrong password, an account with no password credential, an account locked out through a different identifier, an account an operator has blocked, and a wrong password against a suspended or deactivated account. The responses are deliberately identical in body, timing, DB round trips and Redis ops, so signin is not an account-existence oracle. See core/block/CLAUDE.md.
+
+- Params: `PlatformAuth.AuthSigninParams`
+- Public: no API key, browser-safe
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failed |
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `INVALID_CREDENTIALS` | Invalid credentials (`INVALID_CREDENTIALS`). Returned for every failed attempt, including a correct password offered while the account is locked out or blocked, and a wrong password against a suspended or deactivated account. The body never says which. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `ACCOUNT_SUSPENDED`, `ACCOUNT_DEACTIVATED` | The account is suspended (`ACCOUNT_SUSPENDED`) or deactivated (`ACCOUNT_DEACTIVATED`). Only reachable once the caller has proven the password — a wrong password against such an account is a 401. |
+| 429 | `RateLimitError` | `RATE_LIMITED`, `TOO_MANY_ATTEMPTS` | Too many attempts for this identifier (`TOO_MANY_ATTEMPTS`). Two counters produce it, both keyed purely by the submitted identifier: a burst limit of 5 attempts per minute, and a 15-minute lock after 4 failed attempts. Both fire on the same attempt for a registered and an unregistered identifier. Per-IP limit: rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const token = await platform.auth.signin({ identifier: "user@example.com", password: "MySecurePassword123" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-auth-signin)
+
+### `platform.auth.signup(params, options?)`
+
+`POST /v1/auth/signup` → `PlatformAuth.Token`
+
+Create a new account and sign in.
+
+- Params: `PlatformAuth.AuthSignupParams`
+- Public: no API key, browser-safe
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failed |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const token = await platform.auth.signup({ email: "user@example.com", password: "MySecurePassword123", username: "john_doe" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-auth-signup)
+
+## auth.password
+
+### `platform.auth.password.requestReset(params, options?)`
+
+`POST /v1/auth/password/request-reset` → `void`
+
+Request a password reset email. Neither the response nor its timing reveals whether the email matched an account.
+
+- Params: `PlatformAuth.AuthPasswordRequestResetParams`
+- Public: no API key, browser-safe
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Body failed validation (`email` missing or not an email address). Depends only on the request shape, never on whether an account exists. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: more than 10 requests/min from this IP (strict `auth` bucket). `Retry-After` header set. Per-IP limit: rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.auth.password.requestReset({ email: "user@example.com" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-auth-password-request-reset)
+
+### `platform.auth.password.reset(params, options?)`
+
+`POST /v1/auth/password/reset` → `void`
+
+Reset password using the email-delivered reset token.
+
+- Params: `PlatformAuth.AuthPasswordResetParams`
+- Public: no API key, browser-safe
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `PASSWORD_RESET_INVALID` | Body failed validation, the new password fails the password policy, or the reset token is invalid or expired (`PASSWORD_RESET_INVALID`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: more than 10 requests/min from this IP (strict `auth` bucket). `Retry-After` header set. Per-IP limit: rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.auth.password.reset({ new_password: "MyNewPassword123", token: "123456" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-auth-password-reset)
+
+## introspect
+
+### `platform.introspect.apiKey(options?)`
+
+`POST /v1/introspect/api-key` → `PlatformAuth.IntrospectApiKey`
+
+Resolve a Platform API Key (PAK) to its workspace + IAM-style policy. Downstream services use this with a 60s LRU cache and evaluate the policy via @repo/authz-nestjs evaluatePolicy().
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or malformed `Authorization: Bearer` header, or the PAK is unknown, revoked or expired. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const introspectApiKey = await platform.introspect.apiKey();
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-introspect-api-key)
+
+### `platform.introspect.retrieve(options?)`
+
+`GET /v1/introspect` → `PlatformAuth.Introspect`
+
+Introspect current user with workspace list.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: more than 60 requests/min from this IP (default bucket). Anonymous callers, and callers whose session has been signed out, otherwise get 200 with `is_authenticated: false`, never 401. Per-IP limit: rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const introspect = await platform.introspect.retrieve();
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-introspect)
+
+## introspect.workspaces
+
+### `platform.introspect.workspaces.retrieve(workspaceId, options?)`
+
+`GET /v1/introspect/workspaces/{workspace_id}` → `PlatformAuth.IntrospectWorkspace`
+
+Introspect caller's membership + effective policy + enabled services in a workspace.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing or invalid session. Also a session that has been signed out (`SESSION_REVOKED`). |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found (unknown slug or id). Known workspaces the caller is not a member of answer 200 with `is_member: false`. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const introspectWorkspace = await platform.introspect.workspaces.retrieve("workspace");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-introspect-workspaces-workspace-id)
+
+## me
+
+### `platform.me.retrieve(options?)`
+
+`GET /v1/me` → `PlatformAuth.MeProfile`
+
+Read the caller's account profile.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | No session. |
+| 404 | `NotFoundError` | `NOT_FOUND` | No account row for the session principal. Should never fire for a valid session — surfaced for SDKs. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const meProfile = await platform.me.retrieve();
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-me)
+
+## me.avatar
+
+### `platform.me.avatar.clear(options?)`
+
+`DELETE /v1/me/avatar` → `void`
+
+Clear the caller's avatar and delete the stored object.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | No session. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.me.avatar.clear();
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#delete-v1-me-avatar)
+
+### `platform.me.avatar.upload(params, options?)`
+
+`POST /v1/me/avatar` → `PlatformAuth.AvatarUrl`
+
+Upload (or replace) the caller's avatar. PNG/JPEG/WEBP only — SVG is rejected because user-uploaded SVG from a productcraft.co origin is a stored-XSS vector. ≤2 MB. Magic bytes are sniffed; a mislabeled file is rejected.
+
+- Params: `PlatformAuth.MeAvatarUploadParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid file: wrong mimetype, oversized, or content does not match the declared type. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | No session. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const avatarUrl = await platform.me.avatar.upload({ file: new File(["…"], "image.png", { type: "image/png" }) });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-me-avatar)
+
+## me.hiddenGuides
+
+### `platform.me.hiddenGuides.hide(key, options?)`
+
+`PUT /v1/me/hidden-guides/{key}` → `PlatformAuth.HiddenGuide`
+
+Hide a getting-started guide for the caller.
+
+Idempotent: hiding a guide that is already hidden returns it unchanged, with its first `hidden_at`. At most 200 are kept; hiding one more drops the oldest.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | The key is not a valid guide key. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | No session. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller authenticated with a non-human principal (e.g. a workspace API key). Hidden guides are a person's console preference. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const hiddenGuide = await platform.me.hiddenGuides.hide("key");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#put-v1-me-hidden-guides-key)
+
+### `platform.me.hiddenGuides.list(options?)`
+
+`GET /v1/me/hidden-guides` → `PlatformAuth.HiddenGuides`
+
+List the getting-started guides the caller has hidden.
+
+Every guide the caller has hidden in the console, newest first. Hiding is presentation only: the setup status behind a guide is unchanged.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | No session. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller authenticated with a non-human principal (e.g. a workspace API key). Hidden guides are a person's console preference. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const hiddenGuides = await platform.me.hiddenGuides.list();
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-me-hidden-guides)
+
+### `platform.me.hiddenGuides.reset(options?)`
+
+`DELETE /v1/me/hidden-guides` → `void`
+
+Show every getting-started guide again.
+
+Removes every hidden guide for the caller, `all` included. Idempotent.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | No session. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller authenticated with a non-human principal (e.g. a workspace API key). Hidden guides are a person's console preference. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.me.hiddenGuides.reset();
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#delete-v1-me-hidden-guides)
+
+### `platform.me.hiddenGuides.unhide(key, options?)`
+
+`DELETE /v1/me/hidden-guides/{key}` → `void`
+
+Show a hidden getting-started guide again.
+
+Idempotent: showing a guide that is not hidden is a no-op.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | The key is not a valid guide key. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | No session. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller authenticated with a non-human principal (e.g. a workspace API key). Hidden guides are a person's console preference. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.me.hiddenGuides.unhide("key");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#delete-v1-me-hidden-guides-key)
+
+## me.profile
+
+### `platform.me.profile.update(params?, options?)`
+
+`PATCH /v1/me/profile` → `PlatformAuth.MeProfile`
+
+Update the caller's profile. Currently only `displayName` is editable. An empty body is a no-op that returns the current profile. Cookie/JWT only — this is a human-self-service surface, not a PAK-mutation surface.
+
+- Params: `PlatformAuth.MeProfileUpdateParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failed (e.g. displayName outside 1-128 chars). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | No session. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller authenticated with a non-human principal (e.g. PAK). Profile is per-human; only the human owner can mutate their own row. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const meProfile = await platform.me.profile.update({ display_name: "string" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#patch-v1-me-profile)
+
+## oauth.connections
+
+### `platform.oauth.connections.delete(grantId, options?)`
+
+`DELETE /v1/oauth/connections/{grant_id}` → `void`
+
+Disconnect a client.
+
+Revokes the whole grant family — the grant, its authorization codes, its refresh tokens and every live access token — in one transaction.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, invalid or expired bearer token. |
+| 404 | `NotFoundError` | `NOT_FOUND` | No such connection for this human. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.oauth.connections.delete("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#delete-v1-oauth-connections-grant-id)
+
+### `platform.oauth.connections.list(params?, options?)`
+
+`GET /v1/oauth/connections` → `PagePromise<PlatformAuth.ConnectedClient>`
+
+List clients this human has connected.
+
+The user-facing half of revocation: which third-party clients hold a grant, in which workspace, carrying which policy.
+
+- Params: `PlatformAuth.OauthConnectionListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Malformed `cursor`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, invalid or expired bearer token. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const connection of platform.oauth.connections.list()) {
+  console.log(connection);
+}
+const page = await platform.oauth.connections.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-oauth-connections)
+
+## oauth.workspaces.connections
+
+### `platform.oauth.workspaces.connections.delete(workspaceId, grantId, options?)`
+
+`DELETE /v1/oauth/workspaces/{workspace_id}/connections/{grant_id}` → `void`
+
+Disconnect a client on behalf of the workspace.
+
+Revokes the whole grant family for a grant made by any member of this workspace — the lever a workspace owner needs when an employee leaves and their MCP client is still running. Requires `workspace.connection.revoke`.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, invalid or expired bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | Not a member, or lacks `workspace.connection.revoke`. |
+| 404 | `NotFoundError` | `NOT_FOUND` | No such connection in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.oauth.workspaces.connections.delete("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#delete-v1-oauth-workspaces-workspace-id-connections-grant-id)
+
+### `platform.oauth.workspaces.connections.list(workspaceId, params?, options?)`
+
+`GET /v1/oauth/workspaces/{workspace_id}/connections` → `PagePromise<PlatformAuth.ConnectedClient>`
+
+List every client connected to a workspace.
+
+The workspace-side half of revocation, for owners and admins: every grant made against this workspace, by any member, including grants made by people who have since left. Requires `workspace.connection.read`.
+
+- Params: `PlatformAuth.OauthWorkspaceConnectionListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Malformed `cursor`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, invalid or expired bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | Not a member, or lacks `workspace.connection.read`. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const connection of platform.oauth.workspaces.connections.list("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b")) {
+  console.log(connection);
+}
+const page = await platform.oauth.workspaces.connections.list("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", {}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-oauth-workspaces-workspace-id-connections)
+
+### `platform.oauth.workspaces.connections.restore(workspaceId, grantId, options?)`
+
+`POST /v1/oauth/workspaces/{workspace_id}/connections/{grant_id}/restore` → `void`
+
+Lift a workspace revocation so the member may reconnect.
+
+A workspace revocation is durable: the member re-running the connect flow does not undo it, so an administrator has to. This clears the block only — every token minted under the old grant stays revoked and the member still has to approve a fresh consent screen. Requires `workspace.connection.revoke`.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | Not a member, or lacks `workspace.connection.revoke`. |
+| 404 | `NotFoundError` | `NOT_FOUND` | No such connection in this workspace. |
+| 409 | `ConflictError` | `CONFLICT` | The connection was not revoked by an administrator — there is nothing to lift. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.oauth.workspaces.connections.restore("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-oauth-workspaces-workspace-id-connections-grant-id-restore)
+
+## sessions
+
+### `platform.sessions.delete(id, options?)`
+
+`DELETE /v1/session/{id}` → `PlatformAuth.RevokeSession`
+
+Revoke one of the caller's own sessions. Takes effect immediately — the refresh token stops working straight away, not at the end of its window.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `id` is not a UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Unauthorized |
+| 404 | `NotFoundError` | `NOT_FOUND` | No such session, or it belongs to somebody else — deliberately the same response, so this cannot be used to probe which session ids exist. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const revokeSession = await platform.sessions.delete("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#delete-v1-session-id)
+
+### `platform.sessions.list(options?)`
+
+`GET /v1/session` → `PlatformAuth.SessionListResponse`
+
+List active sessions.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Unauthorized |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const result = await platform.sessions.list();
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-session)
+
+### `platform.sessions.revokeOthers(options?)`
+
+`POST /v1/session/revoke-others` → `PlatformAuth.RevokeOtherSessions`
+
+Sign out every other session of the caller, keeping the one this request was made with. Takes effect immediately for the revoked sessions. Idempotent: a repeat call revokes 0.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Unauthorized |
+| 409 | `ConflictError` | `CONFLICT` | The access token maps to no session (minted before sessions tracked token ids), so the current session cannot be kept. Sign in again. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const revokeOtherSessions = await platform.sessions.revokeOthers();
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-session-revoke-others)
+
+## stats
+
+### `platform.stats.retrieve(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/stats` → `PlatformAuth.WorkspaceStats`
+
+Workspace stats.
+
+Member count, active platform API keys, admin changes in the window with a daily series, the last admin change and the last API-key use, for the console dashboard.
+
+Admin changes are workspace audit events that record a mutation. Reads (any action ending `.read`), sign-ins (`auth.signin.succeeded`) and MCP tool-call rows (`workspace.mcp_tool.*`) are not counted, so opening the console does not move the numbers. Days are UTC. Counts and timestamps only: no actor identifiers. Cached for up to 60 seconds (`generated_at`).
+
+- Params: `PlatformAuth.StatsRetrieveParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `window` is not one of 1d, 7d, 30d, or `workspaceId` is the slug of a workspace the caller can read rather than its UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, invalid or expired bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member of the workspace (`NOT_A_MEMBER`) or lacks `workspace.audit.read` on it. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this id (or slug). Same answer as the service's other workspace routes. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const workspaceStats = await platform.stats.retrieve();
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces-workspace-id-stats)
+
+## verification
+
+### `platform.verification.resend(options?)`
+
+`POST /v1/verification/resend` → `PlatformAuth.Feedback`
+
+Resend verification email.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Unauthorized |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const feedback = await platform.verification.resend();
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-verification-resend)
+
+### `platform.verification.verify(params, options?)`
+
+`POST /v1/verification/verify` → `PlatformAuth.Feedback`
+
+Verify an email code.
+
+- Params: `PlatformAuth.VerificationVerifyParams`
+- Public: no API key, browser-safe
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid or expired verification code |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const feedback = await platform.verification.verify({ code: "a1b2c3d4…" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-verification-verify)
+
+## wellKnown
+
+### `platform.wellKnown.jwks(options?)`
+
+`GET /.well-known/jwks.json` → `PlatformAuth.Jwks`
+
+Public JWKS for verifying platform-issued JWTs (issuer `https://api.auth.productcraft.co`).
+
+- Public: no API key, browser-safe
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const jwks = await platform.wellKnown.jwks();
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-well-known-jwks-json)
+
+### `platform.wellKnown.oauthAuthorizationServer(options?)`
+
+`GET /.well-known/oauth-authorization-server` → `PlatformAuth.AuthorizationServerMetadata`
+
+OAuth 2.1 authorization server metadata (RFC 8414).
+
+Discovery document for third-party clients (Claude Desktop, Cursor, the ProductCraft MCP server). PKCE with `S256` is mandatory; no other code-challenge method is advertised or accepted. `scopes_supported` lists **presets**, not scopes: authority is the policy document on the grant (`authority_model`).
+
+- Public: no API key, browser-safe
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const authorizationServerMetadata = await platform.wellKnown.oauthAuthorizationServer();
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-well-known-oauth-authorization-server)
+
+## workspaces
+
+### `platform.workspaces.create(params, options?)`
+
+`POST /v1/workspaces` → `PlatformAuth.Workspace`
+
+Create a new workspace. Cookie/JWT only — PAKs are workspace-scoped credentials and cannot create new workspaces.
+
+- Params: `PlatformAuth.WorkspaceCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, invalid or expired bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | Caller is a PAK (`pcft_live_*`). Workspace creation requires a human-issued session. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const workspace = await platform.workspaces.create({ display_name: "Acme Corp", slug: "acme-corp" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-workspaces)
+
+### `platform.workspaces.delete(workspaceSlug, options?)`
+
+`DELETE /v1/workspaces/{workspace_slug}` → `void`
+
+Delete a workspace (requires workspace.delete). Cookie/JWT only — irreversible workspace destruction needs a human-attributed audit row.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | Caller is a PAK (`pcft_live_*`). Workspace deletion requires a human-issued session. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.workspaces.delete("workspace");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#delete-v1-workspaces-workspace-slug)
+
+### `platform.workspaces.list(params?, options?)`
+
+`GET /v1/workspaces` → `PagePromise<PlatformAuth.WorkspaceListItem>`
+
+List workspaces the current user belongs to.
+
+- Params: `PlatformAuth.WorkspaceListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Malformed `cursor`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid session. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const workspace of platform.workspaces.list()) {
+  console.log(workspace);
+}
+const page = await platform.workspaces.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces)
+
+### `platform.workspaces.retrieve(workspaceSlug, options?)`
+
+`GET /v1/workspaces/{workspace_slug}` → `PlatformAuth.Workspace`
+
+Get workspace details.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid session. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member of this workspace (`NOT_A_MEMBER`). |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found (unknown slug or id). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const workspace = await platform.workspaces.retrieve("workspace");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces-workspace-slug)
+
+### `platform.workspaces.update(workspaceSlug, params?, options?)`
+
+`PATCH /v1/workspaces/{workspace_slug}` → `PlatformAuth.Workspace`
+
+Update workspace display name, slug, or settings. Slug renames broadcast a `workspace.renamed` event so denormalised consumers (waitlist-api) sync.
+
+- Params: `PlatformAuth.WorkspaceUpdateParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid slug or display name. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, invalid or expired bearer token. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found. |
+| 409 | `ConflictError` | `CONFLICT` | Slug already taken by another workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const workspace = await platform.workspaces.update("workspace", { display_name: "string" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#patch-v1-workspaces-workspace-slug)
+
+## workspaces.apiKeys
+
+### `platform.workspaces.apiKeys.create(workspaceSlug, params, options?)`
+
+`POST /v1/workspaces/{workspace_slug}/api-keys` → `PlatformAuth.MintPak`
+
+Mint a new PAK. Choose what it can do with `preset` (a ready-made set such as `mail-send`) or `policy_ids` (managed policies you wrote), never both. The plaintext `token` is returned ONCE — store it now, then call `GET /v1/api-keys/self` with it to check what it can do. The minter can grant at most their own effective permissions. Cookie/JWT only — PAKs cannot mint other PAKs. Send an `Idempotency-Key` to make a retry safe: a retry of a mint that succeeded mints nothing and answers `409 PAK_ALREADY_MINTED` with that key's `id` (the token itself is never cached).
+
+- Params: `PlatformAuth.WorkspaceApiKeyCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `PAK_NAME_REQUIRED`, `PAK_NAME_TOO_LONG` | Body failed validation (`VALIDATION_ERROR`): neither or both of `policy_ids` and `preset`, an unknown `preset`, an empty `policy_ids`, more than 25 policies, or a blank/overlong `name` (`PAK_NAME_REQUIRED` / `PAK_NAME_TOO_LONG`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing, malformed or invalid session. Also a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is a PAK (`pcft_live_*`) — mint requires a human-issued session; or is not a member (`NOT_A_MEMBER`), lacks `workspace.apikey.create`, or cannot grant one or more actions in the chosen preset or policies. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `POLICY_NOT_FOUND` | Workspace not found, or one of `policy_ids` does not exist in this workspace (`POLICY_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `PAK_ALREADY_MINTED`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `PAK_ALREADY_MINTED`: this `Idempotency-Key` already minted a key (its `id` is in `details`); the token was shown once, so rotate that key for a new one. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const mintPak = await platform.workspaces.apiKeys.create("workspace", { name: "Production social client" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-workspaces-workspace-slug-api-keys)
+
+### `platform.workspaces.apiKeys.delete(workspaceSlug, id, params?, options?)`
+
+`DELETE /v1/workspaces/{workspace_slug}/api-keys/{id}` → `void`
+
+Revoke a PAK. Default behaviour: introspect returns null on the next upstream call; downstream services fail-closed within the 60s cache TTL window. Pass `?force=true` to additionally publish a Redis fan-out that evicts the matching cache entry across every PAK-consuming service immediately — use it when rotating a leaked PAK and the 60s window matters.
+
+- Params: `PlatformAuth.WorkspaceApiKeyDeleteParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `id` is not a UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only). Also a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.apikey.delete`. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `PAK_NOT_FOUND` | Workspace not found, or PAK not found in this workspace (`PAK_NOT_FOUND`). Revoking an already-revoked PAK is a 204 no-op. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.workspaces.apiKeys.delete("workspace", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#delete-v1-workspaces-workspace-slug-api-keys-id)
+
+### `platform.workspaces.apiKeys.list(workspaceSlug, params?, options?)`
+
+`GET /v1/workspaces/{workspace_slug}/api-keys` → `PagePromise<PlatformAuth.PublicApiKey>`
+
+List the API keys in this workspace.
+
+Newest first, as the standard cursor-paginated `{data, pagination}` envelope (20 per page, at most 100). Plaintext tokens are never returned, only prefixes and metadata.
+
+**Deprecated legacy shape:** a request that sends neither `limit` nor `cursor` gets a bare JSON array of every key (capped at 1000), unless its `User-Agent` is a ProductCraft SDK (`productcraft-…`), which always gets the envelope. The array is kept only for `@productcraft/platform-auth` 0.0.x clients and is removed in the platform API's next major version; send `limit` (or use an SDK).
+
+- Params: `PlatformAuth.WorkspaceApiKeyListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Malformed `cursor`, or `include_revoked` is not `true` or `false` (`VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, invalid or expired bearer token. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const apiKey of platform.workspaces.apiKeys.list("workspace")) {
+  console.log(apiKey);
+}
+const page = await platform.workspaces.apiKeys.list("workspace", {}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces-workspace-slug-api-keys)
+
+### `platform.workspaces.apiKeys.preview(workspaceSlug, params?, options?)`
+
+`POST /v1/workspaces/{workspace_slug}/api-keys/preview` → `PlatformAuth.PakGrantPreview`
+
+Describe the key a mint with this `preset` or these `policy_ids` would create, without creating anything: what it could do in plain sentences, and whether you may mint it. Read-only, so it takes no `Idempotency-Key`. Powers the review step of the console key wizard.
+
+- Params: `PlatformAuth.WorkspaceApiKeyPreviewParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Body failed validation (`VALIDATION_ERROR`): neither or both of `policy_ids` and `preset`, an unknown `preset`, or an empty or oversized `policy_ids`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing, malformed or invalid session. Also a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is a PAK, is not a member (`NOT_A_MEMBER`), or lacks `workspace.apikey.create`. A key you could not mint is NOT a 403 here: it comes back with `grantable: false`. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `POLICY_NOT_FOUND` | Workspace not found, or one of `policy_ids` does not exist in this workspace (`POLICY_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const pakGrantPreview = await platform.workspaces.apiKeys.preview("workspace", { policy_ids: ["11111111-1111-1111-1111-111111111111"] });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-workspaces-workspace-slug-api-keys-preview)
+
+### `platform.workspaces.apiKeys.retrieve(workspaceSlug, id, options?)`
+
+`GET /v1/workspaces/{workspace_slug}/api-keys/{id}` → `PlatformAuth.PublicApiKey`
+
+Get a single PAK by id.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `id` is not a UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.apikey.read`. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `PAK_NOT_FOUND` | Workspace not found, or PAK not found in this workspace (`PAK_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const publicApiKey = await platform.workspaces.apiKeys.retrieve("workspace", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces-workspace-slug-api-keys-id)
+
+### `platform.workspaces.apiKeys.rotate(workspaceSlug, id, params?, options?)`
+
+`POST /v1/workspaces/{workspace_slug}/api-keys/{id}/rotate` → `PlatformAuth.RotatePak`
+
+Mint a replacement for an existing PAK, carrying its name, description and policy bindings over. The outgoing key keeps working for `grace_hours` (24 by default) so a fleet can roll over without downtime. The plaintext `token` is returned ONCE. Cookie/JWT only — a PAK cannot rotate a PAK, for the same reason it cannot mint one.
+
+- Params: `PlatformAuth.WorkspaceApiKeyRotateParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | Caller is a PAK (`pcft_live_*`), or cannot grant one or more actions in the bindings being carried across. |
+| 404 | `NotFoundError` | `NOT_FOUND` | PAK not found in this workspace. |
+| 409 | `ConflictError` | `CONFLICT`, `PAK_REVOKED`, `PAK_EXPIRED` | The key is revoked (`PAK_REVOKED`), already expired (`PAK_EXPIRED`), or has no policy bindings to carry across. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const rotatePak = await platform.workspaces.apiKeys.rotate("workspace", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6", { grace_hours: 24 });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-workspaces-workspace-slug-api-keys-id-rotate)
+
+### `platform.workspaces.apiKeys.update(workspaceSlug, id, params?, options?)`
+
+`PATCH /v1/workspaces/{workspace_slug}/api-keys/{id}` → `PlatformAuth.PublicApiKey`
+
+Update a PAK’s name or description (does not touch bindings).
+
+- Params: `PlatformAuth.WorkspaceApiKeyUpdateParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `PAK_NAME_REQUIRED` | `id` is not a UUID, body failed validation, or `name` is blank (`PAK_NAME_REQUIRED`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only). Also a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.apikey.update`. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `PAK_NOT_FOUND` | Workspace not found, or PAK not found in this workspace (`PAK_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `PAK_REVOKED` | PAK is revoked (`PAK_REVOKED`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const publicApiKey = await platform.workspaces.apiKeys.update("workspace", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6", { description: "string" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#patch-v1-workspaces-workspace-slug-api-keys-id)
+
+### `platform.workspaces.apiKeys.updateBindings(workspaceSlug, id, params, options?)`
+
+`PATCH /v1/workspaces/{workspace_slug}/api-keys/{id}/bindings` → `PlatformAuth.PublicApiKey`
+
+Replace the managed-policy bindings on a PAK. Re-runs caller-narrowing on the merged union of statements.
+
+- Params: `PlatformAuth.WorkspaceApiKeyUpdateBindingsParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | One of: bound > 25 policies; merged > 200 statements; one of the policy ids does not exist or lives in a different workspace. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | Caller cannot grant one or more actions in the merged statement set. |
+| 404 | `NotFoundError` | `NOT_FOUND` | PAK not found in this workspace. |
+| 409 | `ConflictError` | `CONFLICT` | Empty bindings — revoke the PAK instead of leaving it unbound. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const publicApiKey = await platform.workspaces.apiKeys.updateBindings("workspace", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6", { policy_ids: ["string"] });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#patch-v1-workspaces-workspace-slug-api-keys-id-bindings)
+
+## workspaces.apiKeys.presets
+
+### `platform.workspaces.apiKeys.presets.list(workspaceSlug, options?)`
+
+`GET /v1/workspaces/{workspace_slug}/api-keys/presets` → `PagePromise<PlatformAuth.PakPreset>`
+
+List the ready-made permission sets a workspace key can be minted with (`preset` on create), each with a label, a description and what it allows in this workspace, in plain sentences. A preset a key has already used reads its stored policy, so edits show.
+
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, malformed or invalid session. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.apikey.read`. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const preset of platform.workspaces.apiKeys.presets.list("workspace")) {
+  console.log(preset);
+}
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces-workspace-slug-api-keys-presets)
+
+## workspaces.auditFeed
+
+### `platform.workspaces.auditFeed.list(workspaceSlug, params?, options?)`
+
+`GET /v1/workspaces/{workspace_slug}/audit-feed` → `PagePromise<PlatformAuth.FeedItem>`
+
+Unified workspace audit feed (cursor-paginated).
+
+Audit timeline for workspace-scoped events — workspace, member, role, invite, service-activation, PAK and OAuth-consent mutations, plus successful sign-ins and completed password resets. Per-app Auth rows are NOT merged in: they live in another database with no cursor that spans both, and they are served by `GET /v1/apps/:appId/audit-logs` (paginated), `.../audit-logs/export` (streamed) and the per-app audit sink. The `sources` field reports that explicitly rather than implying a pending follow-up.
+
+- Params: `PlatformAuth.WorkspaceAuditFeedListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid query params — `actor_id` is not a well-formed UUID, or `cursor` is not a cursor this endpoint minted. `since`/`until` that do not parse as ISO-8601 are ignored rather than rejected, and `sources` silently drops unknown names; an empty result set after those filters still returns 200. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, invalid or expired bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller is signed in but lacks `workspace.audit.read` for this workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | The `:workspaceSlug` path param does not resolve to a workspace the caller can see. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const auditFeed of platform.workspaces.auditFeed.list("workspace")) {
+  console.log(auditFeed);
+}
+const page = await platform.workspaces.auditFeed.list("workspace", {}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces-workspace-slug-audit-feed)
+
+## workspaces.auditLogs
+
+### `platform.workspaces.auditLogs.export(workspaceSlug, params?, options?)`
+
+`GET /v1/workspaces/{workspace_slug}/audit-logs/export` → `Response`
+
+Stream the workspace audit log as NDJSON or CSV, applying the same `?action=` / `?actor_id=` / `?since=` / `?until=` filters as the list. Newest first. Reading the export is itself audited.
+
+The response is streamed: rows are walked in keyset batches and written as they are read, so neither the service nor the client holds the whole log. This is the SOC 2 / GDPR export the platform docs promise. Hard cap of 1,000,000 rows per call; a wider request is refused with 413 before any body is written, so a truncated file can never masquerade as a complete one.
+
+- Params: `PlatformAuth.WorkspaceAuditLogExportParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Unknown `format`, or malformed `since` / `until`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, invalid or expired bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | Caller lacks `workspace.audit.read`. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found. |
+| 413 | `APIError` | `PAYLOAD_TOO_LARGE` | More than 1,000,000 rows match. Narrow the window with `since` / `until` and retry. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const response = await platform.workspaces.auditLogs.export("workspace");
+const text = await response.text();
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces-workspace-slug-audit-logs-export)
+
+### `platform.workspaces.auditLogs.list(workspaceSlug, params?, options?)`
+
+`GET /v1/workspaces/{workspace_slug}/audit-logs` → `PagePromise<PlatformAuth.WorkspaceAuditLogEntry>`
+
+List workspace audit log entries, newest first. Filter by `?action=`, `?actor_id=`, and/or the `?since=` / `?until=` date range. 20/page (max 100), cursor-paginated.
+
+- Params: `PlatformAuth.WorkspaceAuditLogListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Malformed `cursor`, `since`, or `until`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, invalid or expired bearer token. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const auditLog of platform.workspaces.auditLogs.list("workspace")) {
+  console.log(auditLog);
+}
+const page = await platform.workspaces.auditLogs.list("workspace", {}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces-workspace-slug-audit-logs)
+
+## workspaces.avatar
+
+### `platform.workspaces.avatar.clear(workspaceSlug, options?)`
+
+`DELETE /v1/workspaces/{workspace_slug}/avatar` → `void`
+
+Clear the workspace avatar and delete the stored object. Gated by `workspace.settings.update`.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid session. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.settings.update`. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found (unknown slug or id). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.workspaces.avatar.clear("workspace");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#delete-v1-workspaces-workspace-slug-avatar)
+
+### `platform.workspaces.avatar.upload(workspaceSlug, params, options?)`
+
+`POST /v1/workspaces/{workspace_slug}/avatar` → `PlatformAuth.WorkspaceAvatarUrl`
+
+Upload (or replace) the workspace identity avatar. Gated by `workspace.settings.update` (owner + admin). PNG/JPEG/WEBP only, ≤2 MB, magic-byte sniffed. SVG is rejected (stored-XSS).
+
+- Params: `PlatformAuth.WorkspaceAvatarUploadParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, invalid or expired bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | Caller is not a member of this workspace, or lacks workspace.settings.update. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const workspaceAvatarUrl = await platform.workspaces.avatar.upload("workspace", { file: new File(["…"], "image.png", { type: "image/png" }) });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-workspaces-workspace-slug-avatar)
+
+## workspaces.invites
+
+### `platform.workspaces.invites.accept(params, options?)`
+
+`POST /v1/workspaces/invites/accept` → `PlatformAuth.Workspace`
+
+Accept a workspace invite by code. Cookie/JWT only — invite acceptance binds a human identity to a workspace.
+
+- Params: `PlatformAuth.WorkspaceInviteAcceptParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Body failed validation (`code` missing or empty). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing or invalid session. Also a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `EMAIL_NOT_VERIFIED`, `INVITE_EMAIL_MISMATCH` | Caller is a PAK (`pcft_live_*`), email not verified (`EMAIL_NOT_VERIFIED`), or the invite is restricted to a different email (`INVITE_EMAIL_MISMATCH`). |
+| 404 | `NotFoundError` | `NOT_FOUND`, `INVITE_INVALID` | Invite code not found (`INVITE_INVALID`). |
+| 409 | `ConflictError` | `CONFLICT`, `ALREADY_A_MEMBER` | Caller is already a member of this workspace (`ALREADY_A_MEMBER`). |
+| 410 | `APIError` | `GONE`, `INVITE_REVOKED`, `INVITE_EXPIRED`, `INVITE_EXHAUSTED` | Invite revoked (`INVITE_REVOKED`), expired (`INVITE_EXPIRED`) or out of uses (`INVITE_EXHAUSTED`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: more than 10 requests/min from this IP (strict `auth` bucket). `Retry-After` header set. Per-IP limit: rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const workspace = await platform.workspaces.invites.accept({ code: "inv_…" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-workspaces-invites-accept)
+
+### `platform.workspaces.invites.create(workspaceSlug, params?, options?)`
+
+`POST /v1/workspaces/{workspace_slug}/invites` → `PlatformAuth.WorkspaceInvite`
+
+Create a workspace invite link. Cookie/JWT only — invites bring new humans into the workspace.
+
+- Params: `PlatformAuth.WorkspaceInviteCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Body failed validation. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing or invalid session. Also a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `EMAIL_NOT_VERIFIED`, `NOT_A_MEMBER`, `OWNER_ROLE_REQUIRED`, `MEMBER_RANK_EXCEEDED` | Caller is a PAK (`pcft_live_*`), email not verified (`EMAIL_NOT_VERIFIED`), not a member (`NOT_A_MEMBER`), lacks `workspace.member.invite`, a non-owner tried to invite an owner (`OWNER_ROLE_REQUIRED`), or the role holds permissions the caller does not (`MEMBER_RANK_EXCEEDED`). |
+| 404 | `NotFoundError` | `NOT_FOUND`, `ROLE_NOT_FOUND` | Workspace not found, or role not found in this workspace (`ROLE_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const workspaceInvite = await platform.workspaces.invites.create("workspace", { email: "alice@example.com" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-workspaces-workspace-slug-invites)
+
+### `platform.workspaces.invites.delete(workspaceSlug, inviteId, options?)`
+
+`DELETE /v1/workspaces/{workspace_slug}/invites/{invite_id}` → `void`
+
+Revoke a workspace invite. Cookie/JWT only.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing or invalid session. Also a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is a PAK (`pcft_live_*`), not a member of the invite’s workspace (`NOT_A_MEMBER`), or lacks `workspace.member.invite`. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `INVITE_NOT_FOUND` | Workspace not found, or invite not found (`INVITE_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.workspaces.invites.delete("workspace", "invite");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#delete-v1-workspaces-workspace-slug-invites-invite-id)
+
+### `platform.workspaces.invites.list(workspaceSlug, params?, options?)`
+
+`GET /v1/workspaces/{workspace_slug}/invites` → `PagePromise<PlatformAuth.WorkspaceInviteListItem>`
+
+List workspace invites, newest first. Cursor-paginated.
+
+- Params: `PlatformAuth.WorkspaceInviteListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Malformed `cursor`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid session. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.member.invite`. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found (unknown slug or id). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const invite of platform.workspaces.invites.list("workspace")) {
+  console.log(invite);
+}
+const page = await platform.workspaces.invites.list("workspace", {}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces-workspace-slug-invites)
+
+## workspaces.members
+
+### `platform.workspaces.members.delete(workspaceSlug, accountId, options?)`
+
+`DELETE /v1/workspaces/{workspace_slug}/members/{account_id}` → `void`
+
+Remove a member from a workspace (or self-leave).
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing or invalid session. Also a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER`, `MEMBER_RANK_EXCEEDED` | Caller is not a member of this workspace (`NOT_A_MEMBER`), lacks `workspace.member.remove` (not required for self-leave), or the target outranks the caller (`MEMBER_RANK_EXCEEDED`: only an owner can remove an owner, and the target role's permissions must all be held by the caller). |
+| 404 | `NotFoundError` | `NOT_FOUND`, `NOT_A_MEMBER` | Workspace not found, or target account is not a member (`NOT_A_MEMBER`). |
+| 409 | `ConflictError` | `CONFLICT`, `LAST_MEMBER`, `SOLE_OWNER` | Target is the last member (`LAST_MEMBER`) or the sole owner (`SOLE_OWNER`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.workspaces.members.delete("workspace", "account");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#delete-v1-workspaces-workspace-slug-members-account-id)
+
+### `platform.workspaces.members.list(workspaceSlug, params?, options?)`
+
+`GET /v1/workspaces/{workspace_slug}/members` → `PagePromise<PlatformAuth.WorkspaceMember>`
+
+List workspace members, oldest join first. Narrow with `?q=` (name / username / email substring) and/or `?role=`. Cursor-paginated.
+
+- Params: `PlatformAuth.WorkspaceMemberListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Malformed `cursor`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid session. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.member.read`. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found (unknown slug or id). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const member of platform.workspaces.members.list("workspace")) {
+  console.log(member);
+}
+const page = await platform.workspaces.members.list("workspace", {}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces-workspace-slug-members)
+
+### `platform.workspaces.members.updateRole(workspaceSlug, accountId, params?, options?)`
+
+`PATCH /v1/workspaces/{workspace_slug}/members/{account_id}/role` → `PlatformAuth.UpdateMemberRole`
+
+Update a member's role. Body: { roleId } or { role: "owner"|"admin"|"member" }.
+
+- Params: `PlatformAuth.WorkspaceMemberUpdateRoleParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Body failed validation. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing or invalid session. Also a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER`, `OWNER_ROLE_REQUIRED`, `MEMBER_RANK_EXCEEDED` | Caller is not a member of this workspace (`NOT_A_MEMBER`), lacks `workspace.member.update-role`, a non-owner tried to assign the owner role or change an owner (`OWNER_ROLE_REQUIRED`), or a non-owner tried to change a role to or from one holding permissions the caller lacks (`MEMBER_RANK_EXCEEDED`). Admins may make admins, never owners. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `NOT_A_MEMBER`, `ROLE_NOT_FOUND` | Workspace not found, target account is not a member (`NOT_A_MEMBER`), or role not found in this workspace (`ROLE_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `SOLE_OWNER` | Would demote the only owner (`SOLE_OWNER`). Assign another owner first. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const updateMemberRole = await platform.workspaces.members.updateRole("workspace", "account", { role: "owner" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#patch-v1-workspaces-workspace-slug-members-account-id-role)
+
+## workspaces.policies
+
+### `platform.workspaces.policies.create(workspaceSlug, params, options?)`
+
+`POST /v1/workspaces/{workspace_slug}/policies` → `PlatformAuth.ManagedPolicy`
+
+Create a managed policy. Cookie/JWT only — policy authoring is a human-admin surface.
+
+- Params: `PlatformAuth.WorkspacePolicyCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid policy shape, name, or condition block. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member (`NOT_A_MEMBER`), lacks `workspace.policy.create` (owner and admin hold it by default), or the policy grants an action the caller does not hold. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Name already in use, or the workspace already has 100 policies. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const managedPolicy = await platform.workspaces.policies.create("workspace", {
+  name: "mail-readonly",
+  policy: [{ actions: ["mail.read", "mail.list"], effect: "allow", resources: ["*"] }],
+});
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-workspaces-workspace-slug-policies)
+
+### `platform.workspaces.policies.delete(workspaceSlug, policyId, options?)`
+
+`DELETE /v1/workspaces/{workspace_slug}/policies/{policy_id}` → `PlatformAuth.ManagedPolicyDeleted`
+
+Delete a managed policy. Cascades: API keys lose the binding (deny-all if no other bindings remain); roles fall back to their inline policy column. Owners and admins; a policy bound to a role, or a preset policy, only an owner can delete. Cookie/JWT only.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `OWNER_ROLE_REQUIRED` | Caller lacks `workspace.policy.delete`, or is not an owner and the policy is bound to a role or is a preset policy (`OWNER_ROLE_REQUIRED`). |
+| 404 | `NotFoundError` | `NOT_FOUND`, `POLICY_NOT_FOUND` | Policy not found in this workspace (`POLICY_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const managedPolicyDeleted = await platform.workspaces.policies.delete("workspace", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#delete-v1-workspaces-workspace-slug-policies-policy-id)
+
+### `platform.workspaces.policies.list(workspaceSlug, params?, options?)`
+
+`GET /v1/workspaces/{workspace_slug}/policies` → `PagePromise<PlatformAuth.ManagedPolicy>`
+
+List managed policies in a workspace, alphabetically. 20/page (max 100), cursor-paginated.
+
+- Params: `PlatformAuth.WorkspacePolicyListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Malformed `cursor`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, invalid or expired bearer token. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const policy of platform.workspaces.policies.list("workspace")) {
+  console.log(policy);
+}
+const page = await platform.workspaces.policies.list("workspace", {}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces-workspace-slug-policies)
+
+### `platform.workspaces.policies.retrieve(workspaceSlug, policyId, options?)`
+
+`GET /v1/workspaces/{workspace_slug}/policies/{policy_id}` → `PlatformAuth.ManagedPolicyDetail`
+
+Get a managed policy by id.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, invalid or expired bearer token. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Policy not found in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const managedPolicyDetail = await platform.workspaces.policies.retrieve("workspace", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces-workspace-slug-policies-policy-id)
+
+### `platform.workspaces.policies.update(workspaceSlug, policyId, params?, options?)`
+
+`PATCH /v1/workspaces/{workspace_slug}/policies/{policy_id}` → `PlatformAuth.ManagedPolicyDetail`
+
+Update a managed policy. Owners and admins; a policy bound to a role, or a preset policy, only an owner can edit. Cookie/JWT only — policy authoring is a human-admin surface.
+
+- Params: `PlatformAuth.WorkspacePolicyUpdateParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid policy shape, name, or condition block. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `OWNER_ROLE_REQUIRED` | Caller lacks `workspace.policy.update`, cannot grant one or more requested actions, or is not an owner and the policy is bound to a role or is a preset policy (`OWNER_ROLE_REQUIRED`). |
+| 404 | `NotFoundError` | `NOT_FOUND`, `POLICY_NOT_FOUND` | Policy not found in this workspace (`POLICY_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `POLICY_NAME_TAKEN` | Name already in use (`POLICY_NAME_TAKEN`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const managedPolicyDetail = await platform.workspaces.policies.update("workspace", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6", { description: "Read-only access to all Mail resources" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#patch-v1-workspaces-workspace-slug-policies-policy-id)
+
+## workspaces.policies.actions
+
+### `platform.workspaces.policies.actions.catalog(workspaceSlug, options?)`
+
+`GET /v1/workspaces/{workspace_slug}/policies/actions/catalog` → `PlatformAuth.WorkspaceActionCatalog`
+
+List every known workspace action (catalog of statement actions).
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.policy.read`. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found (unknown slug or id). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const workspaceActionCatalog = await platform.workspaces.policies.actions.catalog("workspace");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces-workspace-slug-policies-actions-catalog)
+
+## workspaces.roles
+
+### `platform.workspaces.roles.create(workspaceSlug, params, options?)`
+
+`POST /v1/workspaces/{workspace_slug}/roles` → `PlatformAuth.WorkspaceRole`
+
+Create a new custom role. Cookie/JWT only — role authoring is a human-admin surface.
+
+- Params: `PlatformAuth.WorkspaceRoleCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `POLICY_INVALID` | Body failed validation, invalid role name, malformed policy, both `policy_id` and `policy` sent, or an action pattern matches no known permission (`POLICY_INVALID`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only). Also a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER`, `ACTIONS_NOT_GRANTABLE` | Caller is not a member of this workspace (`NOT_A_MEMBER`), lacks `workspace.role.create`, or the policy grants actions the caller does not hold (`ACTIONS_NOT_GRANTABLE`). |
+| 404 | `NotFoundError` | `NOT_FOUND`, `POLICY_NOT_FOUND` | Workspace not found, or `policy_id` not found in this workspace (`POLICY_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `ROLE_NAME_TAKEN`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Role name already in use or reserved for a system role (`ROLE_NAME_TAKEN`). Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const workspaceRole = await platform.workspaces.roles.create("workspace", { name: "BillingAdmin" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-workspaces-workspace-slug-roles)
+
+### `platform.workspaces.roles.delete(workspaceSlug, roleId, options?)`
+
+`DELETE /v1/workspaces/{workspace_slug}/roles/{role_id}` → `void`
+
+Delete a custom role (fails if it has members). Cookie/JWT only — role authoring is a human-admin surface.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `roleId` is not a UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only). Also a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.role.delete`. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `ROLE_NOT_FOUND` | Workspace not found, or role not found in this workspace (`ROLE_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `ROLE_SYSTEM_IMMUTABLE`, `ROLE_HAS_MEMBERS` | Role is a system role (`ROLE_SYSTEM_IMMUTABLE`) or still has members (`ROLE_HAS_MEMBERS`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.workspaces.roles.delete("workspace", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#delete-v1-workspaces-workspace-slug-roles-role-id)
+
+### `platform.workspaces.roles.list(workspaceSlug, params?, options?)`
+
+`GET /v1/workspaces/{workspace_slug}/roles` → `PagePromise<PlatformAuth.WorkspaceRole>`
+
+List roles in a workspace. System roles first, then alphabetical. 20/page (max 100), cursor-paginated.
+
+- Params: `PlatformAuth.WorkspaceRoleListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Malformed `cursor`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, invalid or expired bearer token. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const role of platform.workspaces.roles.list("workspace")) {
+  console.log(role);
+}
+const page = await platform.workspaces.roles.list("workspace", {}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces-workspace-slug-roles)
+
+### `platform.workspaces.roles.retrieve(workspaceSlug, roleId, options?)`
+
+`GET /v1/workspaces/{workspace_slug}/roles/{role_id}` → `PlatformAuth.WorkspaceRole`
+
+Get a role + its permissions.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `roleId` is not a UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.role.read`. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `ROLE_NOT_FOUND` | Workspace not found, or role not found in this workspace (`ROLE_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const workspaceRole = await platform.workspaces.roles.retrieve("workspace", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces-workspace-slug-roles-role-id)
+
+### `platform.workspaces.roles.update(workspaceSlug, roleId, params?, options?)`
+
+`PATCH /v1/workspaces/{workspace_slug}/roles/{role_id}` → `PlatformAuth.WorkspaceRole`
+
+Update a role or replace its permission set. Cookie/JWT only — role authoring is a human-admin surface.
+
+- Params: `PlatformAuth.WorkspaceRoleUpdateParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `roleId` is not a UUID, body failed validation, malformed policy, both `policy_id` and `policy` sent, or an action pattern matches no known permission. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED`, `SESSION_REVOKED` | Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only). Also a session that has been signed out (`SESSION_REVOKED`). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER`, `ACTIONS_NOT_GRANTABLE` | Caller is not a member of this workspace (`NOT_A_MEMBER`), lacks `workspace.role.update`, or the policy grants actions the caller does not hold (`ACTIONS_NOT_GRANTABLE`). |
+| 404 | `NotFoundError` | `NOT_FOUND`, `ROLE_NOT_FOUND`, `POLICY_NOT_FOUND` | Workspace, role (`ROLE_NOT_FOUND`) or bound policy (`POLICY_NOT_FOUND`) not found in this workspace. |
+| 409 | `ConflictError` | `CONFLICT`, `ROLE_SYSTEM_IMMUTABLE`, `ROLE_NAME_TAKEN` | System roles cannot be renamed, edited or bound (`ROLE_SYSTEM_IMMUTABLE`), or the new name is taken (`ROLE_NAME_TAKEN`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const workspaceRole = await platform.workspaces.roles.update("workspace", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6", { description: "string" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#patch-v1-workspaces-workspace-slug-roles-role-id)
+
+## workspaces.services
+
+### `platform.workspaces.services.disable(workspaceSlug, service, options?)`
+
+`DELETE /v1/workspaces/{workspace_slug}/services/{service}` → `void`
+
+Disable a service (settings are retained).
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `SERVICE_UNKNOWN` | Unknown service name (`SERVICE_UNKNOWN`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.service.disable`. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found (unknown slug or id). |
+| 409 | `ConflictError` | `CONFLICT`, `SERVICE_NOT_ENABLED` | Service is not currently enabled (`SERVICE_NOT_ENABLED`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await platform.workspaces.services.disable("workspace", "service");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#delete-v1-workspaces-workspace-slug-services-service)
+
+### `platform.workspaces.services.enable(workspaceSlug, service, params?, options?)`
+
+`POST /v1/workspaces/{workspace_slug}/services/{service}` → `PlatformAuth.WorkspaceServiceState`
+
+Enable (or re-enable) a service for this workspace.
+
+- Params: `PlatformAuth.WorkspaceServiceEnableParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `SERVICE_UNKNOWN` | Unknown service name (`SERVICE_UNKNOWN`) or body failed validation. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.service.enable`. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found (unknown slug or id). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const workspaceServiceState = await platform.workspaces.services.enable("workspace", "service", { settings: {} });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#post-v1-workspaces-workspace-slug-services-service)
+
+### `platform.workspaces.services.list(workspaceSlug, options?)`
+
+`GET /v1/workspaces/{workspace_slug}/services` → `PlatformAuth.ListWorkspaceServices`
+
+List services activated on this workspace. Complete — one row per product, not paginated.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.service.read`. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found (unknown slug or id). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const listWorkspaceServices = await platform.workspaces.services.list("workspace");
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#get-v1-workspaces-workspace-slug-services)
+
+### `platform.workspaces.services.updateSettings(workspaceSlug, service, params?, options?)`
+
+`PATCH /v1/workspaces/{workspace_slug}/services/{service}/settings` → `PlatformAuth.WorkspaceServiceState`
+
+Replace the settings jsonb for an active service.
+
+- Params: `PlatformAuth.WorkspaceServiceUpdateSettingsParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `SERVICE_UNKNOWN` | Unknown service name (`SERVICE_UNKNOWN`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only). |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `NOT_A_MEMBER` | Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.service.enable`. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `SERVICE_NOT_ACTIVATED` | Workspace not found, or the service was never activated on it (`SERVICE_NOT_ACTIVATED`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const workspaceServiceState = await platform.workspaces.services.updateSettings("workspace", "service", { default_sender: "noreply@acme.com" });
+```
+
+[HTTP reference](https://productcraft.co/docs/platform/api-reference#patch-v1-workspaces-workspace-slug-services-service-settings)
+
+## Error codes
+
+`err.code` on an `APIError` is one of these (an open set: new codes may appear).
+
+| Code | Meaning |
+|---|---|
+| `BAD_REQUEST` | The request is malformed (not valid JSON, a bad header, an unusable parameter). |
+| `VALIDATION_ERROR` | One or more request fields are invalid; `errors` lists each field (`param`, `message`, `code`). |
+| `UNAUTHORIZED` | No credentials, or the token or API key is invalid, expired or revoked. |
+| `PAYMENT_REQUIRED` | The workspace has no credit or plan for this operation. |
+| `FORBIDDEN` | The caller is authenticated but not allowed to do this. |
+| `NOT_FOUND` | The resource does not exist, or belongs to another workspace or app. |
+| `METHOD_NOT_ALLOWED` | The route does not accept this HTTP method. |
+| `NOT_ACCEPTABLE` | The route cannot produce the requested content type. |
+| `REQUEST_TIMEOUT` | The request took too long to arrive. |
+| `CONFLICT` | The request conflicts with the current state of the resource. |
+| `GONE` | The resource existed but has been removed for good. |
+| `PRECONDITION_FAILED` | A precondition header did not match. |
+| `PAYLOAD_TOO_LARGE` | The request body is over the size limit. |
+| `UNSUPPORTED_MEDIA_TYPE` | The request body is not in a content type the route accepts. |
+| `UNPROCESSABLE_ENTITY` | The request is well-formed but cannot be carried out. |
+| `PRECONDITION_REQUIRED` | The route requires a precondition header. |
+| `RATE_LIMITED` | Too many requests; retry after the `Retry-After` header. |
+| `INTERNAL_SERVER_ERROR` | An unexpected server error. Retrying is safe for idempotent requests; quote `request_id` to support. |
+| `NOT_IMPLEMENTED` | The server does not support this operation. |
+| `BAD_GATEWAY` | An upstream service returned an invalid response. |
+| `SERVICE_UNAVAILABLE` | The service or one of its dependencies is temporarily unavailable; retry. |
+| `GATEWAY_TIMEOUT` | An upstream service did not answer in time; retry. |
+| `SERVICE_NOT_ENABLED` | The workspace has not enabled this product. |
+| `INVALID_CREDENTIALS` | The credentials were not accepted. |
+| `SESSION_REVOKED` | The session behind this token was signed out or revoked. |
+| `MCP_NOT_PERMITTED` | An MCP (agent) token cannot call this route. |
+| `MCP_WORKSPACE_MISMATCH` | The MCP token was issued for a different workspace. |
+| `PAK_NOT_PERMITTED` | A workspace API key cannot call this route. |
+| `ACTIONS_NOT_GRANTABLE` | The policy grants actions the caller does not hold. |
+| `IDEMPOTENCY_KEY_REUSE` | The `Idempotency-Key` was already used with a different body or route. |
+| `IDEMPOTENCY_KEY_REQUIRED` | This operation requires an `Idempotency-Key` header. |
+| `IDEMPOTENCY_IN_PROGRESS` | A request with the same `Idempotency-Key` is still running. Retry after `Retry-After` seconds with the same key to get its response. |
+| `WEBHOOK_ENDPOINT_LIMIT` | The workspace has the maximum number of webhook endpoints. |
+| `WEBHOOK_ENDPOINT_NOT_FOUND` | No webhook endpoint with this id in this workspace. |
+| `WEBHOOK_ENDPOINT_NOT_SUBSCRIBED` | The endpoint is not subscribed to this event type. |
+| `WEBHOOK_EVENT_NOT_FOUND` | No webhook event with this id in this workspace. |
+| `WEBHOOK_EVENT_TYPE_UNKNOWN` | The event type is not one this product sends. |
+| `ACCOUNT_DEACTIVATED` | Account deactivated. |
+| `ACCOUNT_SUSPENDED` | Account suspended. |
+| `ALREADY_A_MEMBER` | Already a member. |
+| `CROSS_ORIGIN_REJECTED` | The request came from an origin that is not allowed for this cookie-authenticated route. |
+| `EMAIL_NOT_VERIFIED` | Verify the account email first. |
+| `INVITE_EMAIL_MISMATCH` | The invite was sent to a different email address. |
+| `INVITE_EXHAUSTED` | Invite exhausted. |
+| `INVITE_EXPIRED` | Invite expired. |
+| `INVITE_INVALID` | Invite invalid. |
+| `INVITE_NOT_FOUND` | Invite not found. |
+| `INVITE_REVOKED` | Invite revoked. |
+| `LAST_MEMBER` | The workspace's last member cannot leave; delete the workspace instead. |
+| `MEMBER_RANK_EXCEEDED` | You cannot manage a member whose role ranks above yours. |
+| `NOT_A_MEMBER` | The caller is not a member of this workspace. |
+| `OAUTH_GRANT_ADMIN_REVOKED` | An admin revoked this OAuth grant. |
+| `OWNER_ROLE_REQUIRED` | Only an owner can do this. |
+| `PAK_ALREADY_MINTED` | This Idempotency-Key already minted an API key; its token is shown once. Rotate that key (its `id` is in `details`) for a new token. |
+| `PAK_EXPIRED` | Pak expired. |
+| `PAK_NAME_REQUIRED` | An API key needs a name. |
+| `PAK_NAME_TOO_LONG` | The API key name is too long. |
+| `PAK_NOT_FOUND` | Pak not found. |
+| `PAK_REVOKED` | Pak revoked. |
+| `PASSWORD_RESET_INVALID` | The password reset code is invalid or expired. |
+| `POLICY_INVALID` | The policy document is invalid. |
+| `POLICY_NAME_TAKEN` | Policy name taken. |
+| `POLICY_NOT_FOUND` | Policy not found. |
+| `ROLE_HAS_MEMBERS` | The role still has members; move them first. |
+| `ROLE_NAME_TAKEN` | Role name taken. |
+| `ROLE_NOT_FOUND` | Role not found. |
+| `ROLE_SYSTEM_IMMUTABLE` | System roles (owner, admin, member) cannot be changed or deleted. |
+| `SERVICE_NOT_ACTIVATED` | The product is not activated for this workspace. |
+| `SERVICE_UNKNOWN` | No product with this name. |
+| `SOLE_OWNER` | The workspace's only owner cannot leave or be removed; transfer ownership first. |
+| `TOO_MANY_ATTEMPTS` | Too many attempts; wait before trying again. |
+| `WORKSPACE_KEY_REQUIRED` | This route needs a workspace API key. |