{"openapi":"3.0.0","paths":{"/v1/auth/signup":{"post":{"operationId":"AuthenticationController_signup","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignUpDto"}}}},"responses":{"200":{"description":"Token response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Validation failed","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[],"summary":"Create a new account and sign in","tags":["authentication"],"x-pc-sdk":{"resource":"auth","method":"signup","bind":[],"paginated":false,"public":true}}},"/v1/auth/signin":{"post":{"description":"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 and timing, so sign-in never reveals whether an account exists.\n\nAn account with two-step sign-in on answers `200` with a challenge instead of tokens (`mfa_required: true`, `mfa_token`, `factors`): finish with `POST /v1/auth/mfa/verify`. Tell the two apart by `mfa_required`. The challenge is only ever returned for a correct password.","operationId":"AuthenticationController_signin","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignInDto"}}}},"responses":{"200":{"description":"Tokens, or (two-step sign-in on) a challenge to finish with `POST /v1/auth/mfa/verify`.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/TokenResponseDto"},{"$ref":"#/components/schemas/MfaChallengeResponseDto"}]}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Validation failed","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"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.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","INVALID_CREDENTIALS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"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.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","ACCOUNT_SUSPENDED","ACCOUNT_DEACTIVATED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"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.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED","TOO_MANY_ATTEMPTS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[],"summary":"Sign in with email/username and password","tags":["authentication"],"x-pc-sdk":{"resource":"auth","method":"signin","bind":[],"paginated":false,"public":true}}},"/v1/auth/refresh":{"post":{"operationId":"AuthenticationController_refresh","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshDto"}}}},"responses":{"200":{"description":"Token response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Validation failed or invalid token","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[],"summary":"Refresh access token using refresh token","tags":["authentication"],"x-pc-sdk":{"resource":"auth","method":"refresh","bind":[],"paginated":false,"public":true}}},"/v1/auth/logout":{"post":{"operationId":"AuthenticationController_logout","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogoutDto"}}}},"responses":{"204":{"description":"Logout successful (no content)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Validation failed or invalid token","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[],"summary":"Logout by revoking refresh token","tags":["authentication"],"x-pc-sdk":{"resource":"auth","method":"logout","bind":[],"paginated":false,"public":true}}},"/v1/auth/logout-current":{"post":{"operationId":"AuthenticationController_logoutCurrent","parameters":[],"responses":{"204":{"description":"Logout successful (no content)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing or invalid access token","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Revoke the server-side session tied to the caller’s current access token","tags":["authentication"],"x-pc-sdk":{"resource":"auth","method":"logoutCurrent","bind":[],"paginated":false}}},"/v1/auth/password/request-reset":{"post":{"operationId":"PasswordController_requestPasswordReset","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestPasswordResetDto"}}}},"responses":{"204":{"description":"Reset request accepted. Identical whether or not the email matched an account — in status, body, cost, and in what the server is left doing afterwards (see PasswordService.requestPasswordReset). Accepted is not delivered: if the address matched an account the mail was handed to the broker, but a broker outage is logged server-side and still answers 204, so never treat this status as proof an email was sent.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Body failed validation (`email` missing or not an email address). Depends only on the request shape, never on whether an account exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"429":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"]}},"security":[],"summary":"Request a password reset email. Neither the response nor its timing reveals whether the email matched an account.","tags":["authentication"],"x-pc-sdk":{"resource":"auth.password","method":"requestReset","bind":[],"paginated":false,"public":true}}},"/v1/auth/password/reset":{"post":{"operationId":"PasswordController_resetPassword","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetPasswordDto"}}}},"responses":{"204":{"description":"Password reset; all active sessions revoked.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Body failed validation, the new password fails the password policy, or the reset token is invalid or expired (`PASSWORD_RESET_INVALID`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR","PASSWORD_RESET_INVALID"]},"429":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"]}},"security":[],"summary":"Reset password using the email-delivered reset token.","tags":["authentication"],"x-pc-sdk":{"resource":"auth.password","method":"reset","bind":[],"paginated":false,"public":true}}},"/v1/auth/mfa/send-code":{"post":{"description":"Sends a 6-digit code (valid 5 minutes) to the email factor. One send per 30 seconds, 3 per sign-in.","operationId":"AuthMfaController_sendCode","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MfaSendCodeDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeSentDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`VALIDATION_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"The `mfa_token` is unknown, expired, already used or out of tries (`MFA_CHALLENGE_INVALID`): sign in again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","MFA_CHALLENGE_INVALID"]},"404":{"description":"No email factor with this id on the account (`MFA_FACTOR_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","MFA_FACTOR_NOT_FOUND"]},"429":{"description":"Sent less than 30 seconds ago, or 3 codes already went out for this sign-in (`TOO_MANY_ATTEMPTS`). Per-IP limit: rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED","TOO_MANY_ATTEMPTS"]}},"security":[],"summary":"Email a sign-in code","tags":["authentication"],"x-pc-sdk":{"resource":"auth.mfa","method":"sendCode","bind":[],"paginated":false,"public":true}}},"/v1/auth/mfa/webauthn/options":{"post":{"description":"A single-use WebAuthn challenge bound to this sign-in, for `navigator.credentials.get()`. Browser-only.","operationId":"AuthMfaController_webauthnOptions","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MfaTokenDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebauthnRequestOptionsDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`VALIDATION_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"The `mfa_token` is unknown, expired, already used or out of tries (`MFA_CHALLENGE_INVALID`): sign in again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","MFA_CHALLENGE_INVALID"]},"404":{"description":"The account has no passkey (`MFA_FACTOR_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","MFA_FACTOR_NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[],"summary":"Get passkey options for the second step","tags":["authentication"],"x-pc-sdk":false}},"/v1/auth/mfa/verify":{"post":{"description":"Send exactly one of `{factor_id, code}` (authenticator app or email), `{recovery_code}` or `{factor_id, webauthn}`. A right answer returns the session tokens, exactly like a sign-in without two-step. A wrong one spends one of the challenge's 5 tries. Not idempotent: the answer is a session.","operationId":"AuthMfaController_verify","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MfaVerifyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Not exactly one way of answering (`VALIDATION_ERROR`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"The answer was wrong (`MFA_CODE_INVALID`; the challenge survives until its 5 tries are spent), or The `mfa_token` is unknown, expired, already used or out of tries (`MFA_CHALLENGE_INVALID`): sign in again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","MFA_CODE_INVALID","MFA_CHALLENGE_INVALID"]},"403":{"description":"The account was suspended (`ACCOUNT_SUSPENDED`) or deactivated (`ACCOUNT_DEACTIVATED`) meanwhile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","ACCOUNT_SUSPENDED","ACCOUNT_DEACTIVATED"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[],"summary":"Finish sign-in with the second step","tags":["authentication"],"x-pc-sdk":{"resource":"auth.mfa","method":"verify","bind":[],"paginated":false,"public":true}}},"/v1/auth/step-up":{"get":{"description":"Whether sensitive actions are allowed right now (a second step, or the sign-in itself, in the last 10 minutes), until when, and how to step up. `methods`: `totp` / `email` / `webauthn` / `recovery_code` for an account with factors, `password` for one without, `reauthenticate` (sign in again) for one with neither.","operationId":"StepUpController_status","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StepUpStatusDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"No session, or the session was signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"The caller is a workspace API key or an OAuth/MCP token (`HUMAN_SESSION_REQUIRED`): step-up does not apply to them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","HUMAN_SESSION_REQUIRED"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get the session's step-up state","tags":["authentication"],"x-pc-sdk":{"resource":"auth.stepUp","method":"retrieve","bind":[],"paginated":false}},"post":{"description":"Send exactly one of `{factor_id, code}`, `{recovery_code}`, `{factor_id, webauthn}` or, for an account without factors, `{password}`. Sensitive actions on this session are then allowed for 10 minutes. 5 failures per 15 minutes per session. Not idempotent.","operationId":"StepUpController_verify","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StepUpVerifyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StepUpResultDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Not exactly one way of answering (`VALIDATION_ERROR`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"Wrong code or passkey (`MFA_CODE_INVALID`), wrong password or a password offered by an account that has factors (`INVALID_CREDENTIALS`). No session, or the session was signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","MFA_CODE_INVALID","INVALID_CREDENTIALS","SESSION_REVOKED"]},"403":{"description":"The caller is a workspace API key or an OAuth/MCP token (`HUMAN_SESSION_REQUIRED`): step-up does not apply to them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","HUMAN_SESSION_REQUIRED"]},"429":{"description":"5 failed attempts on this session in 15 minutes (`TOO_MANY_ATTEMPTS`). Per-IP limit: rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED","TOO_MANY_ATTEMPTS"]}},"security":[{"bearer":[]}],"summary":"Confirm it is you (step-up)","tags":["authentication"],"x-pc-sdk":{"resource":"auth.stepUp","method":"verify","bind":[],"paginated":false}}},"/v1/auth/step-up/send-code":{"post":{"description":"Sends a 6-digit code (valid 5 minutes) to the email factor. One send per 30 seconds.","operationId":"StepUpController_sendCode","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StepUpSendCodeDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeSentDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`VALIDATION_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"No session, or the session was signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"The caller is a workspace API key or an OAuth/MCP token (`HUMAN_SESSION_REQUIRED`): step-up does not apply to them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","HUMAN_SESSION_REQUIRED"]},"404":{"description":"No email factor with this id (`MFA_FACTOR_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","MFA_FACTOR_NOT_FOUND"]},"429":{"description":"A code went out less than 30 seconds ago (`TOO_MANY_ATTEMPTS`). Per-IP limit: rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED","TOO_MANY_ATTEMPTS"]}},"security":[{"bearer":[]}],"summary":"Email a step-up code","tags":["authentication"],"x-pc-sdk":{"resource":"auth.stepUp","method":"sendCode","bind":[],"paginated":false}}},"/v1/auth/step-up/webauthn/options":{"post":{"description":"A single-use WebAuthn challenge bound to this session. Browser-only.","operationId":"StepUpController_webauthnOptions","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebauthnRequestOptionsDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"No session, or the session was signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"The caller is a workspace API key or an OAuth/MCP token (`HUMAN_SESSION_REQUIRED`): step-up does not apply to them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","HUMAN_SESSION_REQUIRED"]},"404":{"description":"The account has no passkey (`MFA_FACTOR_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","MFA_FACTOR_NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get passkey options for step-up","tags":["authentication"],"x-pc-sdk":false}},"/v1/me/mfa":{"get":{"description":"Whether two-step sign-in is on, the active factors, how many unused recovery codes are left, and the workspaces that require it of this account (with the deadline and whether access is already blocked).","operationId":"MeMfaController_overview","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MfaOverviewDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"No session, or the session was signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"The caller is a workspace API key or an OAuth/MCP token (`HUMAN_SESSION_REQUIRED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","HUMAN_SESSION_REQUIRED"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get the caller's two-step sign-in methods","tags":["me"],"x-pc-sdk":{"resource":"me.mfa","method":"retrieve","bind":[],"paginated":false}}},"/v1/me/mfa/totp":{"post":{"description":"Creates a pending TOTP factor (SHA-1, 6 digits, 30 s) and returns its secret, `otpauth://` URI and QR code. Confirm with a code to turn it on. Starting again replaces a pending one. Not idempotent and takes no `Idempotency-Key`: the answer carries a secret (an authenticator seed, a ceremony challenge or recovery codes) that a replay cache must not hold.","operationId":"MeMfaController_startTotp","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartFactorDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TotpEnrollmentDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`VALIDATION_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"No session, or the session was signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"The caller is a workspace API key or an OAuth/MCP token (`HUMAN_SESSION_REQUIRED`). Or the account already has a factor and this session has not confirmed it is you in the last 10 minutes (`STEP_UP_REQUIRED`, `details.methods` lists how).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","HUMAN_SESSION_REQUIRED","STEP_UP_REQUIRED"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Start adding an authenticator app","tags":["me"],"x-pc-sdk":{"resource":"me.mfa.totp","method":"start","bind":[],"paginated":false}}},"/v1/me/mfa/totp/{factor_id}/confirm":{"post":{"description":"Checks one current code. When this is the account's first factor the answer carries 10 recovery codes, exactly once. Not idempotent and takes no `Idempotency-Key`: the answer carries a secret (an authenticator seed, a ceremony challenge or recovery codes) that a replay cache must not hold.","operationId":"MeMfaController_confirmTotp","parameters":[{"name":"factor_id","required":true,"in":"path","description":"Factor id.","schema":{"type":"string","format":"uuid"},"example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmCodeDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactorActivatedDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Wrong code or credential (`MFA_CODE_INVALID`), or `VALIDATION_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR","MFA_CODE_INVALID"]},"401":{"description":"No session, or the session was signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"The caller is a workspace API key or an OAuth/MCP token (`HUMAN_SESSION_REQUIRED`). Or the account already has a factor and this session has not confirmed it is you in the last 10 minutes (`STEP_UP_REQUIRED`, `details.methods` lists how).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","HUMAN_SESSION_REQUIRED","STEP_UP_REQUIRED"]},"404":{"description":"No pending factor with this id: start again (`MFA_FACTOR_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","MFA_FACTOR_NOT_FOUND"]},"429":{"description":"Five wrong answers on this session in 15 minutes (`TOO_MANY_ATTEMPTS`). Per-IP limit: rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED","TOO_MANY_ATTEMPTS"]}},"security":[{"bearer":[]}],"summary":"Turn on a pending authenticator app","tags":["me"],"x-pc-sdk":{"resource":"me.mfa.totp","method":"confirm","bind":[],"paginated":false}}},"/v1/me/mfa/email":{"post":{"description":"Creates a pending email factor bound to the account's verified primary email and sends it a code (valid 5 minutes). Not idempotent and takes no `Idempotency-Key`: the answer carries a secret (an authenticator seed, a ceremony challenge or recovery codes) that a replay cache must not hold.","operationId":"MeMfaController_startEmail","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartFactorDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailEnrollmentDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`VALIDATION_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"No session, or the session was signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"The caller is a workspace API key or an OAuth/MCP token (`HUMAN_SESSION_REQUIRED`). Or the account already has a factor and this session has not confirmed it is you in the last 10 minutes (`STEP_UP_REQUIRED`, `details.methods` lists how).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","HUMAN_SESSION_REQUIRED","STEP_UP_REQUIRED"]},"409":{"description":"The account email is not verified (`EMAIL_NOT_VERIFIED`), or email codes are already on (`MFA_FACTOR_EXISTS`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","EMAIL_NOT_VERIFIED","MFA_FACTOR_EXISTS"]},"429":{"description":"A code went out less than 30 seconds ago (`TOO_MANY_ATTEMPTS`). Per-IP limit: rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED","TOO_MANY_ATTEMPTS"]}},"security":[{"bearer":[]}],"summary":"Start adding email codes","tags":["me"],"x-pc-sdk":{"resource":"me.mfa.email","method":"start","bind":[],"paginated":false}}},"/v1/me/mfa/email/{factor_id}/confirm":{"post":{"description":"Checks the emailed code. Not idempotent and takes no `Idempotency-Key`: the answer carries a secret (an authenticator seed, a ceremony challenge or recovery codes) that a replay cache must not hold.","operationId":"MeMfaController_confirmEmail","parameters":[{"name":"factor_id","required":true,"in":"path","description":"Factor id.","schema":{"type":"string","format":"uuid"},"example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmCodeDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactorActivatedDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Wrong code or credential (`MFA_CODE_INVALID`), or `VALIDATION_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR","MFA_CODE_INVALID"]},"401":{"description":"No session, or the session was signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"The caller is a workspace API key or an OAuth/MCP token (`HUMAN_SESSION_REQUIRED`). Or the account already has a factor and this session has not confirmed it is you in the last 10 minutes (`STEP_UP_REQUIRED`, `details.methods` lists how).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","HUMAN_SESSION_REQUIRED","STEP_UP_REQUIRED"]},"404":{"description":"No pending factor with this id: start again (`MFA_FACTOR_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","MFA_FACTOR_NOT_FOUND"]},"409":{"description":"The account email changed since the code was sent (`EMAIL_NOT_VERIFIED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","EMAIL_NOT_VERIFIED"]},"429":{"description":"Five wrong answers on this session in 15 minutes (`TOO_MANY_ATTEMPTS`). Per-IP limit: rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED","TOO_MANY_ATTEMPTS"]}},"security":[{"bearer":[]}],"summary":"Turn on pending email codes","tags":["me"],"x-pc-sdk":{"resource":"me.mfa.email","method":"confirm","bind":[],"paginated":false}}},"/v1/me/mfa/webauthn":{"post":{"description":"Creates a pending passkey factor and returns `PublicKeyCredentialCreationOptions` for `navigator.credentials.create()` (relying party `productcraft.co`). Browser-only, so not in the SDKs. Not idempotent and takes no `Idempotency-Key`: the answer carries a secret (an authenticator seed, a ceremony challenge or recovery codes) that a replay cache must not hold.","operationId":"MeMfaController_startWebauthn","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartFactorDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebauthnEnrollmentDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`VALIDATION_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"No session, or the session was signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"The caller is a workspace API key or an OAuth/MCP token (`HUMAN_SESSION_REQUIRED`). Or the account already has a factor and this session has not confirmed it is you in the last 10 minutes (`STEP_UP_REQUIRED`, `details.methods` lists how).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","HUMAN_SESSION_REQUIRED","STEP_UP_REQUIRED"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Start adding a passkey","tags":["me"],"x-pc-sdk":false}},"/v1/me/mfa/webauthn/{factor_id}/confirm":{"post":{"description":"Verifies the credential `navigator.credentials.create()` produced for this factor's challenge. Browser-only. Not idempotent and takes no `Idempotency-Key`: the answer carries a secret (an authenticator seed, a ceremony challenge or recovery codes) that a replay cache must not hold.","operationId":"MeMfaController_confirmWebauthn","parameters":[{"name":"factor_id","required":true,"in":"path","description":"Factor id.","schema":{"type":"string","format":"uuid"},"example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmWebauthnDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactorActivatedDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Wrong code or credential (`MFA_CODE_INVALID`), or `VALIDATION_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR","MFA_CODE_INVALID"]},"401":{"description":"No session, or the session was signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"The caller is a workspace API key or an OAuth/MCP token (`HUMAN_SESSION_REQUIRED`). Or the account already has a factor and this session has not confirmed it is you in the last 10 minutes (`STEP_UP_REQUIRED`, `details.methods` lists how).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","HUMAN_SESSION_REQUIRED","STEP_UP_REQUIRED"]},"404":{"description":"No pending factor with this id: start again (`MFA_FACTOR_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","MFA_FACTOR_NOT_FOUND"]},"409":{"description":"This passkey is already registered (`MFA_FACTOR_EXISTS`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","MFA_FACTOR_EXISTS"]},"429":{"description":"Five wrong answers on this session in 15 minutes (`TOO_MANY_ATTEMPTS`). Per-IP limit: rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED","TOO_MANY_ATTEMPTS"]}},"security":[{"bearer":[]}],"summary":"Turn on a pending passkey","tags":["me"],"x-pc-sdk":false}},"/v1/me/mfa/factors/{factor_id}":{"patch":{"operationId":"MeMfaController_rename","parameters":[{"name":"factor_id","required":true,"in":"path","description":"Factor id.","schema":{"type":"string","format":"uuid"},"example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenameFactorDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MfaFactorDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`VALIDATION_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"No session, or the session was signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"The caller is a workspace API key or an OAuth/MCP token (`HUMAN_SESSION_REQUIRED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","HUMAN_SESSION_REQUIRED"]},"404":{"description":"No active factor with this id (`MFA_FACTOR_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","MFA_FACTOR_NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Rename a factor","tags":["me"],"x-pc-sdk":{"resource":"me.mfa.factors","method":"update","bind":[],"paginated":false}},"delete":{"description":"Needs step-up. Removing the last factor turns two-step sign-in off and deletes the recovery codes; refused while a workspace requires it.","operationId":"MeMfaController_remove","parameters":[{"name":"factor_id","required":true,"in":"path","description":"Factor id.","schema":{"type":"string","format":"uuid"},"example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"responses":{"204":{"description":"Removed.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"No session, or the session was signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"The caller is a workspace API key or an OAuth/MCP token (`HUMAN_SESSION_REQUIRED`). Or this session has not confirmed it is you in the last 10 minutes (`STEP_UP_REQUIRED`, `details.methods` lists how).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","HUMAN_SESSION_REQUIRED","STEP_UP_REQUIRED"]},"404":{"description":"No active factor with this id (`MFA_FACTOR_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","MFA_FACTOR_NOT_FOUND"]},"409":{"description":"It is the last factor and a workspace requires two-step sign-in (`MFA_REQUIRED_BY_WORKSPACE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","MFA_REQUIRED_BY_WORKSPACE"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Remove a factor","tags":["me"],"x-pc-sdk":{"resource":"me.mfa.factors","method":"delete","bind":[],"paginated":false}}},"/v1/me/mfa/recovery-codes":{"post":{"description":"Needs step-up. Returns 10 new single-use codes; every previous code stops working. Not idempotent and takes no `Idempotency-Key`: the answer carries a secret (an authenticator seed, a ceremony challenge or recovery codes) that a replay cache must not hold.","operationId":"MeMfaController_regenerate","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryCodesDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"No session, or the session was signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"The caller is a workspace API key or an OAuth/MCP token (`HUMAN_SESSION_REQUIRED`). Or this session has not confirmed it is you in the last 10 minutes (`STEP_UP_REQUIRED`, `details.methods` lists how).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","HUMAN_SESSION_REQUIRED","STEP_UP_REQUIRED"]},"409":{"description":"Two-step sign-in is off (`MFA_ENROLLMENT_REQUIRED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","MFA_ENROLLMENT_REQUIRED"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Replace the recovery codes","tags":["me"],"x-pc-sdk":{"resource":"me.mfa.recoveryCodes","method":"regenerate","bind":[],"paginated":false}}},"/v1/auth/oauth/{provider}/start":{"get":{"operationId":"OAuthController_start","parameters":[{"name":"provider","required":true,"in":"path","description":"OAuth provider id. Providers are gated on env-var configuration; unconfigured providers 400 with UNKNOWN_OAUTH_PROVIDER.","schema":{"enum":["apple","google","github"],"type":"string"},"example":"google"},{"name":"return_to","required":true,"in":"query","schema":{"type":"string"},"description":"Absolute URL the user lands on after a successful signin. Must match the `OAUTH_RETURN_TO_ORIGINS` allowlist (CSV, wildcards supported as `https://*.productcraft.co`)."}],"responses":{"302":{"description":"Redirect to provider authorize URL.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Invalid `return_to` or unknown provider.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"summary":"Begin a federated sign-in flow; 302s to the provider authorize URL.","tags":["OAuth Sign-In"],"x-pc-sdk":false}},"/v1/auth/oauth/{provider}/callback":{"post":{"operationId":"OAuthController_callback","parameters":[{"name":"provider","required":true,"in":"path","schema":{"enum":["apple","google","github"],"type":"string"},"description":"The sign-in provider: `google`, `github` or `apple`.","example":"google"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallbackBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthCallbackResultDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Unknown / expired state, provider state mismatch, or unknown provider id.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Provider token verification failed, nonce replayed, or downstream identity could not be resolved.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"summary":"Complete a federated sign-in. auth-ui proxies the provider redirect (query params for Google/GitHub, form_post body for Apple) into this endpoint and uses the returned `tokens` to set the auth_token cookie.","tags":["OAuth Sign-In"],"x-pc-sdk":false}},"/v1/introspect":{"get":{"operationId":"IntrospectController_introspect","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntrospectResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"]}},"security":[{"bearer":[]},{}],"summary":"Introspect current user with workspace list","tags":["introspect"],"x-pc-sdk":{"resource":"introspect","method":"retrieve","bind":[],"paginated":false}}},"/v1/introspect/workspaces/{workspace_id}":{"get":{"operationId":"IntrospectController_introspectWorkspace","parameters":[{"name":"workspace_id","required":true,"in":"path","schema":{"type":"string"},"description":"Id of the workspace.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntrospectWorkspaceResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing or invalid session. Also a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"404":{"description":"Workspace not found (unknown slug or id). Known workspaces the caller is not a member of answer 200 with `is_member: false`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Introspect caller's membership + effective policy + enabled services in a workspace","tags":["introspect"],"x-pc-sdk":{"resource":"introspect.workspaces","method":"retrieve","bind":[],"paginated":false}}},"/v1/introspect/api-key":{"post":{"operationId":"IntrospectController_introspectApiKey","parameters":[],"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntrospectApiKeyResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing or malformed `Authorization: Bearer` header, or the PAK is unknown, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Resolve a Platform API Key (PAK) to its workspace + IAM-style policy. Call it with the key a request to your backend carried, cache the answer for up to 60 seconds, and allow an action only when the returned `policy` allows it on the resource.","tags":["introspect"],"x-pc-sdk":{"resource":"introspect","method":"apiKey","bind":[],"paginated":false}}},"/v1/workspaces":{"post":{"operationId":"WorkspaceController_createWorkspace","parameters":[{"name":"Idempotency-Key","in":"header","description":"Opaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that deduplicates retries for 24 h. A retry with the same key and body returns the first response with `Idempotent-Replay: true` instead of creating a second resource. The SDKs send one on every create.","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspaceDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceResponseDto"}}},"headers":{"Idempotent-Replay":{"description":"`true` when this response is a replay of an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing, invalid or expired bearer token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Caller is a PAK (`pcft_live_*`). Workspace creation requires a human-issued session. A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","PAK_NOT_PERMITTED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"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).","headers":{"Retry-After":{"description":"Seconds to wait before retrying with the same key (sent with `IDEMPOTENCY_IN_PROGRESS`).","schema":{"type":"integer"}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","IDEMPOTENCY_KEY_REUSE","IDEMPOTENCY_IN_PROGRESS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Create a new workspace. Cookie/JWT only — PAKs are workspace-scoped credentials and cannot create new workspaces.","tags":["workspaces"],"x-pc-sdk":{"resource":"workspaces","method":"create","bind":[],"paginated":false}},"get":{"operationId":"WorkspaceController_listWorkspaces","parameters":[{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Page size. Defaults to 20, clamped to 100.","example":20},{"name":"cursor","required":false,"in":"query","schema":{"type":"string"},"description":"Opaque `next_cursor` from the previous page.","example":"eyJjcmVhdGVkX2F0IjoiMjAyNi0xMS0wMVQwMDowMDowMFoifQ"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListWorkspacesResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Malformed `cursor`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"Missing or invalid session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List workspaces the current user belongs to","tags":["workspaces"],"x-pc-sdk":{"resource":"workspaces","method":"list","bind":[],"paginated":true}}},"/v1/workspaces/{workspace_slug}":{"get":{"operationId":"WorkspaceController_getWorkspace","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing or invalid session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"403":{"description":"Caller is not a member of this workspace (`NOT_A_MEMBER`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER"]},"404":{"description":"Workspace not found (unknown slug or id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get workspace details","tags":["workspaces"],"x-pc-sdk":{"resource":"workspaces","method":"retrieve","bind":[],"paginated":false}},"patch":{"operationId":"WorkspaceController_updateWorkspace","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkspaceDto"}}}},"responses":{"200":{"description":"Workspace updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Invalid slug or display name.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Missing, invalid or expired bearer token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Workspace not found.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Slug already taken by another workspace.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Update workspace display name, slug, or settings. Slug renames broadcast a `workspace.renamed` event so denormalised consumers (waitlist-api) sync.","tags":["workspaces"],"x-pc-sdk":{"resource":"workspaces","method":"update","bind":[],"paginated":false}},"delete":{"operationId":"WorkspaceController_deleteWorkspace","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"}],"responses":{"204":{"description":"Workspace deleted.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"Caller is a PAK (`pcft_live_*`). Workspace deletion requires a human-issued session. Or the session has not confirmed it is you in the last 10 minutes (`STEP_UP_REQUIRED`, `details.methods` lists how; see `POST /v1/auth/step-up`). A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","STEP_UP_REQUIRED","PAK_NOT_PERMITTED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Delete a workspace (requires workspace.delete). Cookie/JWT only — irreversible workspace destruction needs a human-attributed audit row.","tags":["workspaces"],"x-pc-sdk":{"resource":"workspaces","method":"delete","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/avatar":{"post":{"operationId":"WorkspaceController_setAvatar","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"PNG, JPEG, or WEBP image, ≤2 MB. Square images look best."}},"required":["file"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceAvatarUrlResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing, invalid or expired bearer token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Caller is not a member of this workspace, or lacks workspace.settings.update.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"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).","tags":["workspaces"],"x-pc-sdk":{"resource":"workspaces.avatar","method":"upload","bind":[],"paginated":false}},"delete":{"operationId":"WorkspaceController_removeAvatar","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"}],"responses":{"204":{"description":"Avatar cleared.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing or invalid session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"403":{"description":"Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.settings.update`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER"]},"404":{"description":"Workspace not found (unknown slug or id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Clear the workspace avatar and delete the stored object. Gated by `workspace.settings.update`.","tags":["workspaces"],"x-pc-sdk":{"resource":"workspaces.avatar","method":"clear","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/members":{"get":{"operationId":"WorkspaceController_listMembers","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Page size. Defaults to 20, clamped to 100.","example":20},{"name":"cursor","required":false,"in":"query","schema":{"type":"string"},"description":"Opaque `next_cursor` from the previous page.","example":"eyJjcmVhdGVkX2F0IjoiMjAyNi0xMS0wMVQwMDowMDowMFoifQ"},{"name":"q","required":false,"in":"query","schema":{"type":"string"},"description":"Case-insensitive substring matched against the member’s display name, username OR primary email. `%` and `_` are matched literally.","example":"ada"},{"name":"role","required":false,"in":"query","schema":{"type":"string"},"description":"Exact role name the membership is bound to — `owner`, `admin`, `member`, or a custom role’s name. Composes with `q` and with the cursor.","example":"admin"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListWorkspaceMembersResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Malformed `cursor`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"Missing or invalid session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"403":{"description":"Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.member.read`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER"]},"404":{"description":"Workspace not found (unknown slug or id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List workspace members, oldest join first. Narrow with `?q=` (name / username / email substring) and/or `?role=`. Cursor-paginated.","tags":["workspaces"],"x-pc-sdk":{"resource":"workspaces.members","method":"list","bind":[],"paginated":true}}},"/v1/workspaces/{workspace_slug}/members/{account_id}/role":{"patch":{"operationId":"WorkspaceController_updateMemberRole","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"account_id","required":true,"in":"path","schema":{"type":"string"},"description":"Id of the account.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMemberRoleDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMemberRoleResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"Missing or invalid session. Also a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"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. Or a person's session has not confirmed it is you in the last 10 minutes (`STEP_UP_REQUIRED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER","OWNER_ROLE_REQUIRED","MEMBER_RANK_EXCEEDED","STEP_UP_REQUIRED"]},"404":{"description":"Workspace not found, target account is not a member (`NOT_A_MEMBER`), or role not found in this workspace (`ROLE_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","NOT_A_MEMBER","ROLE_NOT_FOUND"]},"409":{"description":"Would demote the only owner (`SOLE_OWNER`). Assign another owner first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","SOLE_OWNER"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Update a member's role. Body: { roleId } or { role: \"owner\"|\"admin\"|\"member\" }.","tags":["workspaces"],"x-pc-sdk":{"resource":"workspaces.members","method":"updateRole","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/members/{account_id}":{"delete":{"operationId":"WorkspaceController_removeMember","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"account_id","required":true,"in":"path","schema":{"type":"string"},"description":"Id of the account.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"responses":{"204":{"description":"Member removed.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing or invalid session. Also a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER","MEMBER_RANK_EXCEEDED"]},"404":{"description":"Workspace not found, or target account is not a member (`NOT_A_MEMBER`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","NOT_A_MEMBER"]},"409":{"description":"Target is the last member (`LAST_MEMBER`) or the sole owner (`SOLE_OWNER`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","LAST_MEMBER","SOLE_OWNER"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Remove a member from a workspace (or self-leave)","tags":["workspaces"],"x-pc-sdk":{"resource":"workspaces.members","method":"delete","bind":[],"paginated":false}}},"/v1/workspaces/invites/accept":{"post":{"operationId":"WorkspaceController_acceptInvite","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptWorkspaceInviteDto"}}}},"responses":{"201":{"description":"The joined workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Body failed validation (`code` missing or empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"Missing or invalid session. Also a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"Caller is a PAK (`pcft_live_*`), email not verified (`EMAIL_NOT_VERIFIED`), or the invite is restricted to a different email (`INVITE_EMAIL_MISMATCH`). A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","EMAIL_NOT_VERIFIED","INVITE_EMAIL_MISMATCH","PAK_NOT_PERMITTED"]},"404":{"description":"Invite code not found (`INVITE_INVALID`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","INVITE_INVALID"]},"409":{"description":"Caller is already a member of this workspace (`ALREADY_A_MEMBER`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","ALREADY_A_MEMBER"]},"410":{"description":"Invite revoked (`INVITE_REVOKED`), expired (`INVITE_EXPIRED`), out of uses (`INVITE_EXHAUSTED`), or the custom role it granted was deleted (`INVITE_ROLE_DELETED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["GONE","INVITE_REVOKED","INVITE_EXPIRED","INVITE_EXHAUSTED","INVITE_ROLE_DELETED"]},"429":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"]}},"security":[{"bearer":[]}],"summary":"Accept a workspace invite by code. Cookie/JWT only — invite acceptance binds a human identity to a workspace.","tags":["workspaces"],"x-pc-sdk":{"resource":"workspaces.invites","method":"accept","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/invites":{"post":{"operationId":"WorkspaceController_createInvite","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"Idempotency-Key","in":"header","description":"Opaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that deduplicates retries for 24 h. A retry with the same key and body returns the first response with `Idempotent-Replay: true` instead of creating a second resource. The SDKs send one on every create.","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspaceInviteDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceInviteResponseDto"}}},"headers":{"Idempotent-Replay":{"description":"`true` when this response is a replay of an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"Missing or invalid session. Also a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"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`). Or the session has not confirmed it is you in the last 10 minutes (`STEP_UP_REQUIRED`). A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","EMAIL_NOT_VERIFIED","NOT_A_MEMBER","OWNER_ROLE_REQUIRED","MEMBER_RANK_EXCEEDED","STEP_UP_REQUIRED","PAK_NOT_PERMITTED"]},"404":{"description":"Workspace not found, or role not found in this workspace (`ROLE_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","ROLE_NOT_FOUND"]},"409":{"description":"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).","headers":{"Retry-After":{"description":"Seconds to wait before retrying with the same key (sent with `IDEMPOTENCY_IN_PROGRESS`).","schema":{"type":"integer"}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","IDEMPOTENCY_KEY_REUSE","IDEMPOTENCY_IN_PROGRESS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Create a workspace invite link. Cookie/JWT only — invites bring new humans into the workspace.","tags":["workspaces"],"x-pc-sdk":{"resource":"workspaces.invites","method":"create","bind":[],"paginated":false}},"get":{"operationId":"WorkspaceController_listInvites","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Page size. Defaults to 20, clamped to 100.","example":20},{"name":"cursor","required":false,"in":"query","schema":{"type":"string"},"description":"Opaque `next_cursor` from the previous page.","example":"eyJjcmVhdGVkX2F0IjoiMjAyNi0xMS0wMVQwMDowMDowMFoifQ"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListWorkspaceInvitesResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Malformed `cursor`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"Missing or invalid session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"403":{"description":"Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.member.invite`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER"]},"404":{"description":"Workspace not found (unknown slug or id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List workspace invites, newest first. Cursor-paginated.","tags":["workspaces"],"x-pc-sdk":{"resource":"workspaces.invites","method":"list","bind":[],"paginated":true}}},"/v1/workspaces/{workspace_slug}/invites/{invite_id}":{"delete":{"operationId":"WorkspaceController_revokeInvite","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"invite_id","required":true,"in":"path","schema":{"type":"string"},"description":"Id of the invite.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"responses":{"204":{"description":"Invite revoked.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing or invalid session. Also a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"Caller is a PAK (`pcft_live_*`), not a member of the invite’s workspace (`NOT_A_MEMBER`), or lacks `workspace.member.invite`. A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER","PAK_NOT_PERMITTED"]},"404":{"description":"Workspace not found, or invite not found (`INVITE_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","INVITE_NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Revoke a workspace invite. Cookie/JWT only.","tags":["workspaces"],"x-pc-sdk":{"resource":"workspaces.invites","method":"delete","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/security":{"get":{"description":"Whether members must use two-step sign-in, since when, and the grace period. Callers holding `workspace.member.read` also get each member's status (enabled, deadline, blocked).","operationId":"WorkspaceSecurityController_get","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceSecurityDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"Not a member (`NOT_A_MEMBER`), or a member past the deadline without two-step sign-in (`MFA_ENROLLMENT_REQUIRED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER","MFA_ENROLLMENT_REQUIRED"]},"404":{"description":"Workspace not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get the workspace security policy","tags":["workspaces"],"x-pc-sdk":{"resource":"workspaces.security","method":"retrieve","bind":[],"paginated":false}},"put":{"description":"Owner only (`workspace.security.update`), a person's session only, and needs step-up. Turning the requirement on needs the caller to have two-step sign-in. Each member then has until max(now, joined) + `grace_period_days` to turn it on; past that, the workspace refuses them until they do. Workspace API keys are not affected. Saving again while it is on keeps the original start date. `PUT` replaces the policy, so it takes no `Idempotency-Key`.","operationId":"WorkspaceSecurityController_update","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkspaceSecurityDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceSecurityDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`VALIDATION_ERROR`: `grace_period_days` must be 0-30.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"Caller is a workspace API key or an MCP grant (`PAK_NOT_PERMITTED` / `MCP_NOT_PERMITTED`), not a member (`NOT_A_MEMBER`), lacks `workspace.security.update`, or the session has not confirmed it is you in the last 10 minutes (`STEP_UP_REQUIRED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","PAK_NOT_PERMITTED","MCP_NOT_PERMITTED","NOT_A_MEMBER","STEP_UP_REQUIRED"]},"404":{"description":"Workspace not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"]},"409":{"description":"Turning the requirement on while the caller has no two-step sign-in (`MFA_ENROLLMENT_REQUIRED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","MFA_ENROLLMENT_REQUIRED"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Change the workspace security policy","tags":["workspaces"],"x-pc-sdk":{"resource":"workspaces.security","method":"update","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/roles":{"get":{"operationId":"WorkspaceRoleController_list","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Page size. Defaults to 20, clamped to 100.","example":20},{"name":"cursor","required":false,"in":"query","schema":{"type":"string"},"description":"Opaque `next_cursor` from the previous page.","example":"eyJjcmVhdGVkX2F0IjoiMjAyNi0xMS0wMVQwMDowMDowMFoifQ"}],"responses":{"200":{"description":"Page of roles with `next_cursor` and `has_more`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListWorkspaceRolesResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Malformed `cursor`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Missing, invalid or expired bearer token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List roles in a workspace. System roles first, then alphabetical. 20/page (max 100), cursor-paginated.","tags":["workspace-roles"],"x-pc-sdk":{"resource":"workspaces.roles","method":"list","bind":[],"paginated":true}},"post":{"operationId":"WorkspaceRoleController_create","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"Idempotency-Key","in":"header","description":"Opaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that deduplicates retries for 24 h. A retry with the same key and body returns the first response with `Idempotent-Replay: true` instead of creating a second resource. The SDKs send one on every create.","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspaceRoleDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceRoleResponseDto"}}},"headers":{"Idempotent-Replay":{"description":"`true` when this response is a replay of an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Body failed validation, invalid role name, malformed policy, both `policy_id` and `policy` sent, or an action pattern matches no known permission (`POLICY_INVALID`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR","POLICY_INVALID"]},"401":{"description":"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`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"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`). A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER","ACTIONS_NOT_GRANTABLE","PAK_NOT_PERMITTED"]},"404":{"description":"Workspace not found, or `policy_id` not found in this workspace (`POLICY_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","POLICY_NOT_FOUND"]},"409":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying with the same key (sent with `IDEMPOTENCY_IN_PROGRESS`).","schema":{"type":"integer"}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","ROLE_NAME_TAKEN","IDEMPOTENCY_KEY_REUSE","IDEMPOTENCY_IN_PROGRESS"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Create a new custom role. Cookie/JWT only — role authoring is a human-admin surface.","tags":["workspace-roles"],"x-pc-sdk":{"resource":"workspaces.roles","method":"create","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/roles/{role_id}":{"get":{"operationId":"WorkspaceRoleController_get","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"role_id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the role.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceRoleResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`roleId` is not a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"403":{"description":"Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.role.read`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER"]},"404":{"description":"Workspace not found, or role not found in this workspace (`ROLE_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","ROLE_NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get a role + its permissions","tags":["workspace-roles"],"x-pc-sdk":{"resource":"workspaces.roles","method":"retrieve","bind":[],"paginated":false}},"patch":{"operationId":"WorkspaceRoleController_update","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"role_id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the role.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkspaceRoleDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceRoleResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`roleId` is not a UUID, body failed validation, malformed policy, both `policy_id` and `policy` sent, or an action pattern matches no known permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"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`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"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`). A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER","ACTIONS_NOT_GRANTABLE","PAK_NOT_PERMITTED"]},"404":{"description":"Workspace, role (`ROLE_NOT_FOUND`) or bound policy (`POLICY_NOT_FOUND`) not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","ROLE_NOT_FOUND","POLICY_NOT_FOUND"]},"409":{"description":"System roles cannot be renamed, edited or bound (`ROLE_SYSTEM_IMMUTABLE`), or the new name is taken (`ROLE_NAME_TAKEN`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","ROLE_SYSTEM_IMMUTABLE","ROLE_NAME_TAKEN"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Update a role or replace its permission set. Cookie/JWT only — role authoring is a human-admin surface.","tags":["workspace-roles"],"x-pc-sdk":{"resource":"workspaces.roles","method":"update","bind":[],"paginated":false}},"delete":{"operationId":"WorkspaceRoleController_delete","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"role_id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the role.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"responses":{"204":{"description":"Custom role deleted.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`roleId` is not a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"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`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.role.delete`. A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER","PAK_NOT_PERMITTED"]},"404":{"description":"Workspace not found, or role not found in this workspace (`ROLE_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","ROLE_NOT_FOUND"]},"409":{"description":"Role is a system role (`ROLE_SYSTEM_IMMUTABLE`) or still has members (`ROLE_HAS_MEMBERS`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","ROLE_SYSTEM_IMMUTABLE","ROLE_HAS_MEMBERS"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Delete a custom role (fails if it has members). Cookie/JWT only — role authoring is a human-admin surface.","tags":["workspace-roles"],"x-pc-sdk":{"resource":"workspaces.roles","method":"delete","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/policies":{"get":{"operationId":"WorkspacePolicyController_list","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Page size. Defaults to 20, clamped to 100.","example":20},{"name":"cursor","required":false,"in":"query","schema":{"type":"string"},"description":"Opaque `next_cursor` from the previous page.","example":"eyJjcmVhdGVkX2F0IjoiMjAyNi0xMS0wMVQwMDowMDowMFoifQ"}],"responses":{"200":{"description":"Page of managed policies with `next_cursor` and `has_more`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListManagedPoliciesResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Malformed `cursor`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Missing, invalid or expired bearer token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List managed policies in a workspace, alphabetically. 20/page (max 100), cursor-paginated.","tags":["workspace-policies"],"x-pc-sdk":{"resource":"workspaces.policies","method":"list","bind":[],"paginated":true}},"post":{"operationId":"WorkspacePolicyController_create","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"Idempotency-Key","in":"header","description":"Opaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that deduplicates retries for 24 h. A retry with the same key and body returns the first response with `Idempotent-Replay: true` instead of creating a second resource. The SDKs send one on every create.","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspacePolicyDto"}}}},"responses":{"201":{"description":"Policy created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedPolicyResponseDto"}}},"headers":{"Idempotent-Replay":{"description":"`true` when this response is a replay of an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Invalid policy shape, name, or condition block.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"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. A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER","PAK_NOT_PERMITTED"]},"409":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying with the same key (sent with `IDEMPOTENCY_IN_PROGRESS`).","schema":{"type":"integer"}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","IDEMPOTENCY_KEY_REUSE","IDEMPOTENCY_IN_PROGRESS"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Create a managed policy. Cookie/JWT only — policy authoring is a human-admin surface.","tags":["workspace-policies"],"x-pc-sdk":{"resource":"workspaces.policies","method":"create","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/policies/actions/catalog":{"get":{"operationId":"WorkspacePolicyController_catalog","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceActionCatalogResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"403":{"description":"Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.policy.read`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER"]},"404":{"description":"Workspace not found (unknown slug or id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List every known workspace action (catalog of statement actions).","tags":["workspace-policies"],"x-pc-sdk":{"resource":"workspaces.policies.actions","method":"catalog","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/policies/{policy_id}":{"get":{"operationId":"WorkspacePolicyController_get","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"policy_id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the policy.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"responses":{"200":{"description":"Policy detail. `binding_count.{pak,role}` reports how many things are currently bound — surface this in delete-confirm UX.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedPolicyDetailResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing, invalid or expired bearer token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Policy not found in this workspace.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get a managed policy by id","tags":["workspace-policies"],"x-pc-sdk":{"resource":"workspaces.policies","method":"retrieve","bind":[],"paginated":false}},"patch":{"operationId":"WorkspacePolicyController_update","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"policy_id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the policy.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkspacePolicyDto"}}}},"responses":{"200":{"description":"Updated policy. `bound_key_count` is the number of live API keys the change applies to.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedPolicyDetailResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Invalid policy shape, name, or condition block.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"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`). A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","OWNER_ROLE_REQUIRED","PAK_NOT_PERMITTED"]},"404":{"description":"Policy not found in this workspace (`POLICY_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","POLICY_NOT_FOUND"]},"409":{"description":"Name already in use (`POLICY_NAME_TAKEN`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","POLICY_NAME_TAKEN"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"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.","tags":["workspace-policies"],"x-pc-sdk":{"resource":"workspaces.policies","method":"update","bind":[],"paginated":false}},"delete":{"operationId":"WorkspacePolicyController_delete","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"policy_id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the policy.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"responses":{"200":{"description":"Policy deleted. `bound_key_count` is the number of live API keys that lost the binding.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedPolicyDeletedResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"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`). A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","OWNER_ROLE_REQUIRED","PAK_NOT_PERMITTED"]},"404":{"description":"Policy not found in this workspace (`POLICY_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","POLICY_NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"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.","tags":["workspace-policies"],"x-pc-sdk":{"resource":"workspaces.policies","method":"delete","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/services":{"get":{"operationId":"WorkspaceServiceController_list","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListWorkspaceServicesResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"403":{"description":"Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.service.read`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER"]},"404":{"description":"Workspace not found (unknown slug or id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List services activated on this workspace. Complete — one row per product, not paginated.","tags":["workspace-services"],"x-pc-sdk":{"resource":"workspaces.services","method":"list","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/services/{service}":{"post":{"operationId":"WorkspaceServiceController_enable","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"service","required":true,"in":"path","schema":{"type":"string"},"description":"The product: `auth`, `mail`, `waitlist`, `social`, `trawl`, `flags` or `notify`.","example":"mail"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnableWorkspaceServiceDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceServiceStateDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Unknown service name (`SERVICE_UNKNOWN`) or body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR","SERVICE_UNKNOWN"]},"401":{"description":"Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"403":{"description":"Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.service.enable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER"]},"404":{"description":"Workspace not found (unknown slug or id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Enable (or re-enable) a service for this workspace","tags":["workspace-services"],"x-pc-sdk":{"resource":"workspaces.services","method":"enable","bind":[],"paginated":false}},"delete":{"operationId":"WorkspaceServiceController_disable","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"service","required":true,"in":"path","schema":{"type":"string"},"description":"The product: `auth`, `mail`, `waitlist`, `social`, `trawl`, `flags` or `notify`.","example":"mail"}],"responses":{"204":{"description":"Service disabled. Settings preserved for re-enable.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Unknown service name (`SERVICE_UNKNOWN`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR","SERVICE_UNKNOWN"]},"401":{"description":"Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"403":{"description":"Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.service.disable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER"]},"404":{"description":"Workspace not found (unknown slug or id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"]},"409":{"description":"Service is not currently enabled (`SERVICE_NOT_ENABLED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","SERVICE_NOT_ENABLED"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Disable a service (settings are retained)","tags":["workspace-services"],"x-pc-sdk":{"resource":"workspaces.services","method":"disable","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/services/{service}/settings":{"patch":{"operationId":"WorkspaceServiceController_updateSettings","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"service","required":true,"in":"path","schema":{"type":"string"},"description":"The product: `auth`, `mail`, `waitlist`, `social`, `trawl`, `flags` or `notify`.","example":"mail"}],"requestBody":{"required":true,"description":"Replaces the per-service settings jsonb entirely. The body is the settings object itself (no wrapper). Service-specific shape — e.g. mail tracks default sender, social tracks ranking weights.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"example":{"default_sender":"noreply@acme.com"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceServiceStateDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Unknown service name (`SERVICE_UNKNOWN`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR","SERVICE_UNKNOWN"]},"401":{"description":"Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"403":{"description":"Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.service.enable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER"]},"404":{"description":"Workspace not found, or the service was never activated on it (`SERVICE_NOT_ACTIVATED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","SERVICE_NOT_ACTIVATED"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Replace the settings jsonb for an active service","tags":["workspace-services"],"x-pc-sdk":{"resource":"workspaces.services","method":"updateSettings","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/api-keys":{"get":{"description":"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.\n\n**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).","operationId":"PlatformApiKeyController_list","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Page size. Defaults to 20, clamped to 100.","example":20},{"name":"cursor","required":false,"in":"query","schema":{"type":"string"},"description":"Opaque `next_cursor` from the previous page.","example":"eyJjcmVhdGVkX2F0IjoiMjAyNi0xMS0wMVQwMDowMDowMFoifQ"},{"name":"include_revoked","required":false,"in":"query","schema":{"type":"boolean","default":true},"description":"Send `false` to leave revoked keys out (the console's default view). Expired keys are still listed: they show what needs replacing. The deprecated bare array ignores it.","example":true}],"responses":{"200":{"description":"One page of keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListPlatformApiKeysResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Malformed `cursor`, or `include_revoked` is not `true` or `false` (`VALIDATION_ERROR`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"Missing, invalid or expired bearer token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List the API keys in this workspace","tags":["platform-api-keys"],"x-pc-sdk":{"resource":"workspaces.apiKeys","method":"list","bind":[],"paginated":true}},"post":{"operationId":"PlatformApiKeyController_create","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"Idempotency-Key","in":"header","description":"Opaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that deduplicates retries for 24 h. A retry with the same key and body mints nothing and answers `409 PAK_ALREADY_MINTED` with the first key's `id` in `details` (the token is shown once and never cached; rotate the key for a new one). The SDKs send one on every create.","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePakDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintPakResponseDto"}}},"headers":{"Idempotent-Replay":{"description":"`true` when this response is a replay of an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"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`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR","PAK_NAME_REQUIRED","PAK_NAME_TOO_LONG"]},"401":{"description":"Missing, malformed or invalid session. Also a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"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; or the session has not confirmed it is you in the last 10 minutes (`STEP_UP_REQUIRED`, `details.methods` lists how). A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER","STEP_UP_REQUIRED","PAK_NOT_PERMITTED"]},"404":{"description":"Workspace not found, or one of `policy_ids` does not exist in this workspace (`POLICY_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","POLICY_NOT_FOUND"]},"409":{"description":"`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).","headers":{"Retry-After":{"description":"Seconds to wait before retrying with the same key (sent with `IDEMPOTENCY_IN_PROGRESS`).","schema":{"type":"integer"}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","PAK_ALREADY_MINTED","IDEMPOTENCY_KEY_REUSE","IDEMPOTENCY_IN_PROGRESS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"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).","tags":["platform-api-keys"],"x-pc-sdk":{"resource":"workspaces.apiKeys","method":"create","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/api-keys/presets":{"get":{"operationId":"PlatformApiKeyController_presets","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListPakPresetsResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing, malformed or invalid session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"403":{"description":"Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.apikey.read`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER"]},"404":{"description":"Workspace not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"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.","tags":["platform-api-keys"],"x-pc-sdk":{"resource":"workspaces.apiKeys.presets","method":"list","bind":[],"paginated":true}}},"/v1/workspaces/{workspace_slug}/api-keys/preview":{"post":{"operationId":"PlatformApiKeyController_preview","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewPakDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PakGrantPreviewDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Body failed validation (`VALIDATION_ERROR`): neither or both of `policy_ids` and `preset`, an unknown `preset`, or an empty or oversized `policy_ids`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"Missing, malformed or invalid session. Also a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"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`. A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER","PAK_NOT_PERMITTED"]},"404":{"description":"Workspace not found, or one of `policy_ids` does not exist in this workspace (`POLICY_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","POLICY_NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"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.","tags":["platform-api-keys"],"x-pc-sdk":{"resource":"workspaces.apiKeys","method":"preview","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/api-keys/{id}/rotate":{"post":{"operationId":"PlatformApiKeyController_rotate","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the api key.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotatePakDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotatePakResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"Caller is a PAK (`pcft_live_*`), or cannot grant one or more actions in the bindings being carried across; or the session has not confirmed it is you in the last 10 minutes (`STEP_UP_REQUIRED`). A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","STEP_UP_REQUIRED","PAK_NOT_PERMITTED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"PAK not found in this workspace.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The key is revoked (`PAK_REVOKED`), already expired (`PAK_EXPIRED`), or has no policy bindings to carry across.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","PAK_REVOKED","PAK_EXPIRED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"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.","tags":["platform-api-keys"],"x-pc-sdk":{"resource":"workspaces.apiKeys","method":"rotate","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/api-keys/{id}/bindings":{"patch":{"operationId":"PlatformApiKeyController_setBindings","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the api key.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetBindingsDto"}}}},"responses":{"200":{"description":"Updated PAK with new bindings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiKeyDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"One of: bound > 25 policies; merged > 200 statements; one of the policy ids does not exist or lives in a different workspace.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"Caller cannot grant one or more actions in the merged statement set, or the session has not confirmed it is you in the last 10 minutes (`STEP_UP_REQUIRED`). A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","STEP_UP_REQUIRED","PAK_NOT_PERMITTED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"PAK not found in this workspace.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Empty bindings — revoke the PAK instead of leaving it unbound.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Replace the managed-policy bindings on a PAK. Re-runs caller-narrowing on the merged union of statements.","tags":["platform-api-keys"],"x-pc-sdk":{"resource":"workspaces.apiKeys","method":"updateBindings","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/api-keys/{id}":{"get":{"operationId":"PlatformApiKeyController_get","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the api key.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiKeyDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`id` is not a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"Missing, malformed or invalid session, or a PAK bearer (this route accepts cookie/JWT sessions only).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"403":{"description":"Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.apikey.read`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER"]},"404":{"description":"Workspace not found, or PAK not found in this workspace (`PAK_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","PAK_NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get a single PAK by id.","tags":["platform-api-keys"],"x-pc-sdk":{"resource":"workspaces.apiKeys","method":"retrieve","bind":[],"paginated":false}},"patch":{"operationId":"PlatformApiKeyController_update","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the api key.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePakDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiKeyDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`id` is not a UUID, body failed validation, or `name` is blank (`PAK_NAME_REQUIRED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR","PAK_NAME_REQUIRED"]},"401":{"description":"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`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.apikey.update`. A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER","PAK_NOT_PERMITTED"]},"404":{"description":"Workspace not found, or PAK not found in this workspace (`PAK_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","PAK_NOT_FOUND"]},"409":{"description":"PAK is revoked (`PAK_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT","PAK_REVOKED"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Update a PAK’s name or description (does not touch bindings).","tags":["platform-api-keys"],"x-pc-sdk":{"resource":"workspaces.apiKeys","method":"update","bind":[],"paginated":false}},"delete":{"operationId":"PlatformApiKeyController_revoke","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the api key.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"},{"name":"force","required":false,"in":"query","description":"When `true`, publish a `pak:revoked` Redis fan-out so subscribed services evict their caches immediately instead of waiting out the 60s TTL.","schema":{"type":"boolean"},"example":true}],"responses":{"204":{"description":"PAK revoked.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`id` is not a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"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`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"Caller is not a member of this workspace (`NOT_A_MEMBER`), or lacks `workspace.apikey.delete`. A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER","PAK_NOT_PERMITTED"]},"404":{"description":"Workspace not found, or PAK not found in this workspace (`PAK_NOT_FOUND`). Revoking an already-revoked PAK is a 204 no-op.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","PAK_NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"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.","tags":["platform-api-keys"],"x-pc-sdk":{"resource":"workspaces.apiKeys","method":"delete","bind":[],"paginated":false}}},"/v1/api-keys/self":{"get":{"operationId":"ApiKeySelfController_self","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeySelfResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"No bearer, or the key is unknown, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"403":{"description":"Signed in with a session or another token instead of a workspace key (`WORKSPACE_KEY_REQUIRED`). Send the `pcft_live_…` key as the bearer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","WORKSPACE_KEY_REQUIRED"]},"404":{"description":"The key was deleted while the request was in flight (`PAK_NOT_FOUND`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND","PAK_NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"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.","tags":["platform-api-keys"],"x-pc-sdk":{"resource":"apiKeys","method":"self","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/audit-logs":{"get":{"operationId":"WorkspaceAuditController_listAuditLogs","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Page size. Defaults to 20, clamped to 100.","example":20},{"name":"cursor","required":false,"in":"query","schema":{"type":"string"},"description":"Opaque `next_cursor` from the previous page.","example":"eyJjcmVhdGVkX2F0IjoiMjAyNi0xMS0wMVQwMDowMDowMFoifQ"},{"name":"action","required":false,"in":"query","schema":{"type":"string"},"description":"Exact-match filter on the action identifier (e.g. `workspace.member.removed`). Mail, Waitlist, Social and Auth actions are reported under the product name (`mail.domain.verified`); the older internal spellings (`envoi.*`, `rally.*`, `agora.*`, `heimdall.*`) are still accepted here and match the same rows.","example":"workspace.member.removed"},{"name":"actor_id","required":false,"in":"query","schema":{"type":"string","format":"uuid"},"description":"Exact-match filter on the acting account UUID. System rows have a null actor and are excluded by this filter.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"},{"name":"since","required":false,"in":"query","schema":{"type":"string","format":"date-time"},"description":"Inclusive lower bound on `created_at`. ISO-8601 date (`2026-05-01`, midnight UTC) or date-time (`2026-05-01T09:00:00Z`). Composes with `action` / `actor_id` / `until` and with the cursor.","example":"2026-11-01T00:00:00Z"},{"name":"until","required":false,"in":"query","schema":{"type":"string","format":"date-time"},"description":"Inclusive upper bound on `created_at`. Same formats as `since`. Note a bare date resolves to midnight UTC, so `until=2026-05-01` excludes that day’s later entries.","example":"2026-12-01T00:00:00Z"}],"responses":{"200":{"description":"Page of audit entries with `next_cursor` and `has_more`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListWorkspaceAuditLogsResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Malformed `cursor`, `since`, or `until`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Missing, invalid or expired bearer token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"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.","tags":["workspace-audit-logs"],"x-pc-sdk":{"resource":"workspaces.auditLogs","method":"list","bind":[],"paginated":true}}},"/v1/workspaces/{workspace_slug}/audit-logs/export":{"get":{"description":"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.","operationId":"WorkspaceAuditController_exportAuditLogs","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"format","required":false,"in":"query","schema":{"type":"string","enum":["ndjson","csv"]},"description":"Defaults to `ndjson`.","example":"ndjson"},{"name":"action","required":false,"in":"query","schema":{"type":"string"},"description":"Exact-match filter on the action identifier, same rules as the list. Mail, Waitlist, Social and Auth actions are reported under the product name (`mail.domain.verified`); the older internal spellings (`envoi.*`, `rally.*`, `agora.*`, `heimdall.*`) are still accepted here and match the same rows.","example":"workspace.member.removed"},{"name":"actor_id","required":false,"in":"query","schema":{"type":"string","format":"uuid"},"description":"Exact-match filter on the acting account UUID, same rules as the list.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"},{"name":"since","required":false,"in":"query","schema":{"type":"string","format":"date-time"},"description":"Inclusive lower bound on `created_at`, same formats as the list.","example":"2026-11-01T00:00:00Z"},{"name":"until","required":false,"in":"query","schema":{"type":"string","format":"date-time"},"description":"Inclusive upper bound on `created_at`, same formats as the list.","example":"2026-12-01T00:00:00Z"}],"responses":{"200":{"description":"Streamed export. `application/x-ndjson` (one JSON object per line) or `text/csv` (RFC 4180, header row first).","content":{"application/x-ndjson":{"schema":{"type":"string","description":"Newline-delimited JSON: one audit-row object per line."}},"text/csv":{"schema":{"type":"string","description":"RFC 4180 CSV, header row first, one audit row per line."}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Unknown `format`, or malformed `since` / `until`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Missing, invalid or expired bearer token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Caller lacks `workspace.audit.read`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Workspace not found.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"413":{"description":"More than 1,000,000 rows match. Narrow the window with `since` / `until` and retry.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["PAYLOAD_TOO_LARGE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"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.","tags":["workspace-audit-logs"],"x-pc-sdk":{"resource":"workspaces.auditLogs","method":"export","bind":[],"paginated":false}}},"/v1/workspaces/{workspace_slug}/audit-feed":{"get":{"description":"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.","operationId":"WorkspaceAuditFeedController_listFeed","parameters":[{"name":"workspace_slug","required":true,"in":"path","schema":{"type":"string"},"description":"Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead.","example":"acme"},{"name":"since","required":false,"in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO-8601 inclusive lower bound on `timestamp`. Items older than `since` are not returned.","example":"2026-11-01T00:00:00Z"},{"name":"until","required":false,"in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO-8601 inclusive upper bound on `timestamp`. Composes with `since`, `action`, `actor_id` and with the cursor. A bare date resolves to midnight UTC, so `until=2026-05-01` excludes that day’s later entries.","example":"2026-12-01T00:00:00Z"},{"name":"action","required":false,"in":"query","schema":{"type":"string"},"description":"Exact-match filter on the action identifier (e.g. `workspace.member.removed`). A partial string matches nothing. Mail, Waitlist, Social and Auth actions are reported under the product name (`mail.domain.verified`); the older internal spellings (`envoi.*`, `rally.*`, `agora.*`, `heimdall.*`) are still accepted here and match the same rows.","example":"workspace.member.removed"},{"name":"actor_id","required":false,"in":"query","schema":{"type":"string","format":"uuid"},"description":"Exact-match filter on the acting account UUID. Must be a well-formed UUID — anything else is a 400, not an empty page. System rows have a null actor and are excluded by this filter.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"},{"name":"changes_only","required":false,"in":"query","schema":{"type":"boolean","default":false},"description":"When `true`, return only admin changes: reads (any action ending `.read`), successful sign-ins (`auth.signin.succeeded`) and MCP tool-call rows (`workspace.mcp_tool.*`) are left out. The same rows the dashboard stats count as admin changes. Composes with every other filter and with the cursor; pass it on every page. Any value other than `true` or `1` means `false`.","example":false},{"name":"cursor","required":false,"in":"query","schema":{"type":"string"},"description":"Opaque cursor from a previous response's `pagination.next_cursor`. Resumes the feed at the same merge boundary.","example":"eyJjcmVhdGVkX2F0IjoiMjAyNi0xMS0wMVQwMDowMDowMFoifQ"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"Per-page cap. Clamped to 1..500; default 100.","example":100},{"name":"sources","required":false,"in":"query","schema":{"type":"string"},"description":"Comma-separated subset of sources to include (e.g. `workspace_audit,heimdall_audit`). Omitted = all enabled sources.","example":"workspace_audit,heimdall_audit"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditFeedResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"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.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Missing, invalid or expired bearer token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"The caller is signed in but lacks `workspace.audit.read` for this workspace.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"The `:workspaceSlug` path param does not resolve to a workspace the caller can see.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Unified workspace audit feed (cursor-paginated)","tags":["workspace-audit-logs"],"x-pc-sdk":{"resource":"workspaces.auditFeed","method":"list","bind":[],"paginated":true}}},"/v1/workspaces/{workspace_id}/stats":{"get":{"description":"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.\n\nAdmin 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`).","operationId":"WorkspaceStatsController_get","parameters":[{"name":"workspace_id","required":true,"in":"path","description":"Workspace id.","schema":{"format":"uuid","type":"string"},"example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"},{"name":"window","required":false,"in":"query","description":"Window for `in_window` and the length of `series`, in UTC days ending today.","schema":{"default":"30d","example":"30d","enum":["1d","7d","30d"],"type":"string"},"example":"30d"}],"responses":{"200":{"description":"Workspace stats.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceStatsDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`window` is not one of 1d, 7d, 30d, or `workspaceId` is the slug of a workspace the caller can read rather than its UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"Missing, invalid or expired bearer token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Caller is not a member of the workspace (`NOT_A_MEMBER`) or lacks `workspace.audit.read` on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","NOT_A_MEMBER"]},"404":{"description":"Workspace not found: no workspace has this id (or slug). Same answer as the service's other workspace routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Workspace stats","tags":["workspace-stats"],"x-pc-sdk":{"resource":"stats","method":"retrieve","bind":["workspace_id"],"paginated":false}}},"/v1/account":{"delete":{"operationId":"AccountController_deleteAccount","parameters":[],"responses":{"204":{"description":"Account deleted. All sessions revoked, and any linked Sign in with Apple grant is queued for revocation with Apple. The revocation is durable and retried in the background, so a 204 does not depend on Apple being reachable.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing, invalid or expired bearer token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"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).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No account row exists for the session principal. Should never fire for a valid session — surfaced for SDKs.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"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.","tags":["account"],"x-pc-sdk":{"resource":"account","method":"erase","bind":[],"paginated":false}}},"/v1/me":{"get":{"operationId":"MeController_getMe","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeProfileDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"No session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No account row for the session principal. Should never fire for a valid session — surfaced for SDKs.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Read the caller's account profile.","tags":["me"],"x-pc-sdk":{"resource":"me","method":"retrieve","bind":[],"paginated":false}}},"/v1/me/profile":{"patch":{"operationId":"MeController_updateProfile","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProfileDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeProfileDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Validation failed (e.g. displayName outside 1-128 chars).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"No session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"The caller authenticated with a non-human principal (e.g. PAK). Profile is per-human; only the human owner can mutate their own row. A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","PAK_NOT_PERMITTED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"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.","tags":["me"],"x-pc-sdk":{"resource":"me.profile","method":"update","bind":[],"paginated":false}}},"/v1/me/avatar":{"post":{"operationId":"MeController_setAvatar","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"PNG, JPEG, or WEBP image, ≤2 MB."}},"required":["file"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarUrlResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Invalid file: wrong mimetype, oversized, or content does not match the declared type.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"No session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"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.","tags":["me"],"x-pc-sdk":{"resource":"me.avatar","method":"upload","bind":[],"paginated":false}},"delete":{"operationId":"MeController_removeAvatar","parameters":[],"responses":{"204":{"description":"Avatar removed (or already absent).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"No session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Clear the caller's avatar and delete the stored object.","tags":["me"],"x-pc-sdk":{"resource":"me.avatar","method":"clear","bind":[],"paginated":false}}},"/v1/me/hidden-guides":{"get":{"description":"Every guide the caller has hidden in the console, newest first. Hiding is presentation only: the setup status behind a guide is unchanged.","operationId":"HiddenGuidesController_list","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HiddenGuidesDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"No session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"The caller authenticated with a non-human principal (e.g. a workspace API key). Hidden guides are a person's console preference. A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","PAK_NOT_PERMITTED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List the getting-started guides the caller has hidden.","tags":["me"],"x-pc-sdk":{"resource":"me.hiddenGuides","method":"list","bind":[],"paginated":false}},"delete":{"description":"Removes every hidden guide for the caller, `all` included. Idempotent.","operationId":"HiddenGuidesController_showAll","parameters":[],"responses":{"204":{"description":"Every guide shows again.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"No session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"The caller authenticated with a non-human principal (e.g. a workspace API key). Hidden guides are a person's console preference. A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","PAK_NOT_PERMITTED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Show every getting-started guide again.","tags":["me"],"x-pc-sdk":{"resource":"me.hiddenGuides","method":"reset","bind":[],"paginated":false}}},"/v1/me/hidden-guides/{key}":{"put":{"description":"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.","operationId":"HiddenGuidesController_hide","parameters":[{"name":"key","required":true,"in":"path","description":"The guide: a surface name, optionally followed by `:` and a resource id, e.g. `dashboard:<workspace id>` or `all`.","schema":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}(:[A-Za-z0-9_-]{1,64})?$"},"example":"dashboard"}],"responses":{"200":{"description":"The guide is hidden.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HiddenGuideDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"The key is not a valid guide key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"No session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"The caller authenticated with a non-human principal (e.g. a workspace API key). Hidden guides are a person's console preference. A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","PAK_NOT_PERMITTED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Hide a getting-started guide for the caller.","tags":["me"],"x-pc-sdk":{"resource":"me.hiddenGuides","method":"hide","bind":[],"paginated":false}},"delete":{"description":"Idempotent: showing a guide that is not hidden is a no-op.","operationId":"HiddenGuidesController_show","parameters":[{"name":"key","required":true,"in":"path","description":"The guide: a surface name, optionally followed by `:` and a resource id, e.g. `dashboard:<workspace id>` or `all`.","schema":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}(:[A-Za-z0-9_-]{1,64})?$"},"example":"dashboard"}],"responses":{"204":{"description":"The guide shows again (or was not hidden).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"The key is not a valid guide key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"No session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"The caller authenticated with a non-human principal (e.g. a workspace API key). Hidden guides are a person's console preference. A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","PAK_NOT_PERMITTED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Show a hidden getting-started guide again.","tags":["me"],"x-pc-sdk":{"resource":"me.hiddenGuides","method":"unhide","bind":[],"paginated":false}}},"/v1/session":{"get":{"operationId":"SessionController_getSessions","parameters":[],"responses":{"200":{"description":"Active sessions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SessionDto"}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List active sessions","tags":["session"],"x-pc-sdk":{"resource":"sessions","method":"list","bind":[],"paginated":false}}},"/v1/session/revoke-others":{"post":{"operationId":"SessionController_revokeOtherSessions","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeOtherSessionsResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"409":{"description":"The access token maps to no session (minted before sessions tracked token ids), so the current session cannot be kept. Sign in again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"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.","tags":["session"],"x-pc-sdk":{"resource":"sessions","method":"revokeOthers","bind":[],"paginated":false}}},"/v1/session/{id}":{"delete":{"operationId":"SessionController_revokeSession","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the session.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"responses":{"200":{"description":"`revoked` is false when the session was already revoked, so repeating the call is safe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeSessionResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`id` is not a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such session, or it belongs to somebody else — deliberately the same response, so this cannot be used to probe which session ids exist.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"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.","tags":["session"],"x-pc-sdk":{"resource":"sessions","method":"delete","bind":[],"paginated":false}}},"/v1/verification/verify":{"post":{"operationId":"VerificationController_verify","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyCodeDto"}}}},"responses":{"200":{"description":"Email verified successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Invalid or expired verification code","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[],"summary":"Verify an email code","tags":["verification"],"x-pc-sdk":{"resource":"verification","method":"verify","bind":[],"paginated":false,"public":true}}},"/v1/verification/resend":{"post":{"operationId":"VerificationController_resend","parameters":[],"responses":{"200":{"description":"Verification email sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Resend verification email","tags":["verification"],"x-pc-sdk":{"resource":"verification","method":"resend","bind":[],"paginated":false}}},"/.well-known/jwks.json":{"get":{"operationId":"JwksController_jwks","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JwksResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[],"summary":"Public JWKS for verifying platform-issued JWTs (issuer `https://api.auth.productcraft.co`).","tags":["jwks"],"x-pc-sdk":{"resource":"wellKnown","method":"jwks","bind":[],"paginated":false,"public":true}}},"/.well-known/oauth-authorization-server":{"get":{"description":"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`).","operationId":"AuthorizationServerMetadataController_metadata","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorizationServerMetadataDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[],"summary":"OAuth 2.1 authorization server metadata (RFC 8414)","tags":["oauth-authorization-server"],"x-pc-sdk":{"resource":"wellKnown","method":"oauthAuthorizationServer","bind":[],"paginated":false,"public":true}}},"/v1/oauth/register":{"post":{"description":"Public endpoint, rate-limited per source IP. Every client registered here is marked **unverified** and stays that way; the consent screen shows the badge. `client_secret` and `registration_access_token` are returned once and stored only as hashes.","operationId":"OAuthRegistrationController_register","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientRegistrationRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientRegistrationResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`invalid_redirect_uri` or `invalid_client_metadata` (RFC 7591 §3.2.2).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"429":{"description":"`invalid_request` — too many registrations from this IP. Per-IP limit: rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponseDto"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"]},"503":{"description":"`temporarily_unavailable` — the rate-limit backend is unreachable, so registration fails closed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["SERVICE_UNAVAILABLE"]}},"summary":"Register an OAuth client dynamically (RFC 7591)","tags":["oauth-authorization-server"],"x-pc-sdk":false}},"/v1/oauth/register/{client_id}":{"get":{"description":"Requires `Authorization: Bearer <registration_access_token>`. The token addresses exactly one registration; presenting it for a different `client_id` fails.","operationId":"OAuthRegistrationController_read","parameters":[{"name":"client_id","required":true,"in":"path","description":"The `client_id` to read.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientMetadataDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"`invalid_client` — bad registration access token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Read a client registration (RFC 7592)","tags":["oauth-authorization-server"],"x-pc-sdk":false},"put":{"description":"Requires `Authorization: Bearer <registration_access_token>`. Only display metadata, redirect URIs and the scope ceiling can change — a client cannot promote itself to verified, nor change its authentication method.","operationId":"OAuthRegistrationController_update","parameters":[{"name":"client_id","required":true,"in":"path","description":"The `client_id` to update.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientRegistrationRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientMetadataDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"`invalid_client` — bad registration access token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Update a client registration (RFC 7592)","tags":["oauth-authorization-server"],"x-pc-sdk":false}},"/v1/oauth/authorize":{"get":{"description":"Requires PKCE with `code_challenge_method=S256`; a session that has been signed out counts as no session; `plain` and a missing challenge are both rejected. `redirect_uri` must match a registered URI exactly, with only the RFC 8252 §7.3 loopback port relaxation. Responds 302 either to sign-in (no session) or to the consent screen.","operationId":"OAuthAuthorizeController_authorize","parameters":[{"name":"products","required":false,"in":"query","description":"Comma-separated products to pre-select on the consent screen (`auth`, `mail`, `waitlist`, `social`, `trawl`, `flags`, `notify`). A pre-selection only: the human decides. Unknown names are ignored.","schema":{"example":"mail,waitlist"},"example":"mail,waitlist"},{"name":"resource","required":false,"in":"query","description":"RFC 8707 resource indicator. Becomes the access token `aud`. It may carry `?products=mail,waitlist`, which pre-selects products on the consent screen and is removed from the audience.","schema":{}},{"name":"state","required":false,"in":"query","schema":{}},{"name":"code_challenge_method","required":true,"in":"query","schema":{"example":"S256"},"example":"S256"},{"name":"code_challenge","required":true,"in":"query","schema":{}},{"name":"scope","required":true,"in":"query","description":"Space-delimited preset names (`readonly`, `mail`, `support`, `full`). A preset resolves to a policy template the human narrows on the consent screen; it is never authority in itself.","schema":{"example":"mail"},"example":"mail"},{"name":"redirect_uri","required":true,"in":"query","schema":{}},{"name":"client_id","required":true,"in":"query","schema":{}},{"name":"response_type","required":true,"in":"query","schema":{"example":"code"},"example":"code"}],"responses":{"302":{"description":"Redirect to sign-in or to the consent screen.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Rendered `{ error, error_description }` when the failure is in `client_id` or `redirect_uri` — those are never bounced to an unvalidated URI.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"summary":"OAuth 2.1 authorization endpoint","tags":["oauth-authorization-server"],"x-pc-sdk":false}},"/v1/oauth/consent/{request_id}":{"get":{"description":"Backs the consent screen (task 002). Readable only by the signed-in human the request was created for; anyone else gets the same 404 a nonexistent request gets.","operationId":"OAuthAuthorizeController_consentRequest","parameters":[{"name":"request_id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the request.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentRequestDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","PAK_NOT_PERMITTED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such pending request for this human.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Request already used.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"410":{"description":"Request expired.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["GONE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Read a pending consent request","tags":["oauth-authorization-server"],"x-pc-sdk":false},"post":{"description":"Approving mints a single-use authorization code bound to the client, the redirect URI, the PKCE challenge, the chosen workspace and the approved policy. The policy is narrowed against the human's own authority through the same `assertCallerCanGrant` the workspace-role and PAK lanes use; a grant that exceeds the granter is refused, never trimmed. Denying returns a redirect carrying `error=access_denied`.\n\nCSRF: the session must be presented as an `Authorization: Bearer` header. The ambient `auth_token` cookie is not accepted on its own, and a request whose `Sec-Fetch-Site` / `Origin` says a browser on another origin is driving it is refused — cookie policy cannot be the only CSRF control on the endpoint that mints a code.","operationId":"OAuthAuthorizeController_decide","parameters":[{"name":"request_id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the request.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentDecisionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentDecisionResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Malformed policy, empty policy, or too many statements.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"Refused before authentication with `CROSS_ORIGIN_REJECTED` when the request carries no bearer or a browser on another origin is driving it. Otherwise: not a member of the chosen workspace, or the approved policy exceeds the human’s own authority — `details.refused_statements` names which statements and why. Also `ACCOUNT_SUSPENDED` / `ACCOUNT_DEACTIVATED` when the account is no longer active, and `OAUTH_GRANT_ADMIN_REVOKED` when a workspace administrator revoked this connection and has not lifted it. A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","CROSS_ORIGIN_REJECTED","ACCOUNT_SUSPENDED","ACCOUNT_DEACTIVATED","OAUTH_GRANT_ADMIN_REVOKED","PAK_NOT_PERMITTED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such pending request for this human.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Request already used.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Record the human’s consent decision","tags":["oauth-authorization-server"],"x-pc-sdk":false}},"/v1/oauth/connections":{"get":{"description":"The user-facing half of revocation: which third-party clients hold a grant, in which workspace, carrying which policy.","operationId":"OAuthAuthorizeController_connections","parameters":[{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Page size. Defaults to 20, clamped to 100.","example":20},{"name":"cursor","required":false,"in":"query","schema":{"type":"string"},"description":"Opaque `next_cursor` from the previous page.","example":"eyJjcmVhdGVkX2F0IjoiMjAyNi0xMS0wMVQwMDowMDowMFoifQ"}],"responses":{"200":{"description":"Page of connections, newest first, with `next_cursor` and `has_more`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectedClientListDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Malformed `cursor`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Missing, invalid or expired bearer token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","PAK_NOT_PERMITTED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List clients this human has connected","tags":["oauth-authorization-server"],"x-pc-sdk":{"resource":"oauth.connections","method":"list","bind":[],"paginated":true}}},"/v1/oauth/connections/{grant_id}":{"delete":{"description":"Revokes the whole grant family — the grant, its authorization codes, its refresh tokens and every live access token — in one transaction.","operationId":"OAuthAuthorizeController_disconnect","parameters":[{"name":"grant_id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the grant.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"responses":{"204":{"description":"Disconnected.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing, invalid or expired bearer token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","PAK_NOT_PERMITTED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such connection for this human.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Disconnect a client","tags":["oauth-authorization-server"],"x-pc-sdk":{"resource":"oauth.connections","method":"delete","bind":[],"paginated":false}}},"/v1/oauth/workspaces/{workspace_id}/connections":{"get":{"description":"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`.","operationId":"OAuthAuthorizeController_workspaceConnections","parameters":[{"name":"workspace_id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the workspace.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Page size. Defaults to 20, clamped to 100.","example":20},{"name":"cursor","required":false,"in":"query","schema":{"type":"string"},"description":"Opaque `next_cursor` from the previous page.","example":"eyJjcmVhdGVkX2F0IjoiMjAyNi0xMS0wMVQwMDowMDowMFoifQ"}],"responses":{"200":{"description":"Page of connections, newest first, with `next_cursor` and `has_more`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectedClientListDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Malformed `cursor`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Missing, invalid or expired bearer token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Not a member, or lacks `workspace.connection.read`. A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","PAK_NOT_PERMITTED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List every client connected to a workspace","tags":["oauth-authorization-server"],"x-pc-sdk":{"resource":"oauth.workspaces.connections","method":"list","bind":[],"paginated":true}}},"/v1/oauth/workspaces/{workspace_id}/connections/{grant_id}":{"delete":{"description":"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`.","operationId":"OAuthAuthorizeController_disconnectWorkspaceConnection","parameters":[{"name":"workspace_id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the workspace.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"},{"name":"grant_id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the grant.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"responses":{"204":{"description":"Disconnected.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing, invalid or expired bearer token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Not a member, or lacks `workspace.connection.revoke`. A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","PAK_NOT_PERMITTED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such connection in this workspace.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Disconnect a client on behalf of the workspace","tags":["oauth-authorization-server"],"x-pc-sdk":{"resource":"oauth.workspaces.connections","method":"delete","bind":[],"paginated":false}}},"/v1/oauth/workspaces/{workspace_id}/connections/{grant_id}/restore":{"post":{"description":"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`.","operationId":"OAuthAuthorizeController_restoreWorkspaceConnection","parameters":[{"name":"workspace_id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the workspace.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"},{"name":"grant_id","required":true,"in":"path","schema":{"format":"uuid","type":"string"},"description":"Id of the grant.","example":"3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"}],"responses":{"204":{"description":"Revocation lifted.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing or invalid session, or a session that has been signed out (`SESSION_REVOKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED","SESSION_REVOKED"]},"403":{"description":"Not a member, or lacks `workspace.connection.revoke`. A workspace API key (`pcft_live_…`) is refused with `PAK_NOT_PERMITTED`: this route needs a person's session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["FORBIDDEN","PAK_NOT_PERMITTED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such connection in this workspace.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["NOT_FOUND"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The connection was not revoked by an administrator — there is nothing to lift.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Lift a workspace revocation so the member may reconnect","tags":["oauth-authorization-server"],"x-pc-sdk":{"resource":"oauth.workspaces.connections","method":"restore","bind":[],"paginated":false}}},"/v1/oauth/token":{"post":{"description":"Accepts `authorization_code` (with a mandatory `code_verifier`) and `refresh_token`. Both credentials are single-use: replaying a code or a refresh token issues nothing and revokes the entire grant family, so anything already minted from that grant stops working immediately.","operationId":"OAuthTokenController_token","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthTokenResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"`invalid_request`, `invalid_grant`, `invalid_scope`, `invalid_target`, or `unsupported_grant_type`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"]},"401":{"description":"`invalid_client` — client authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"summary":"OAuth 2.1 token endpoint","tags":["oauth-authorization-server"],"x-pc-sdk":false}},"/v1/oauth/revoke":{"post":{"description":"Revoking a refresh token takes the whole grant family with it. Always answers 200, including for an unknown token — otherwise the endpoint would be a token-validity oracle.","operationId":"OAuthTokenController_revoke","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevocationRequestDto"}}}},"responses":{"200":{"description":"Revoked, or the token was already unknown.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"`invalid_client` — client authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"summary":"Revoke a token (RFC 7009)","tags":["oauth-authorization-server"],"x-pc-sdk":false}},"/v1/oauth/introspect":{"post":{"description":"Client-authenticated, and a client may only introspect its own tokens. `policy` is the ceiling the human approved; `effective_policy` is that intersected with the human's current workspace policy, resolved live on every call with no cache, so a demotion or an offboarding lands on the next call rather than at token expiry.","operationId":"OAuthTokenController_introspect","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntrospectionRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntrospectionResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"`invalid_client` — client authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"]},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"summary":"Introspect an access token (RFC 7662)","tags":["oauth-authorization-server"],"x-pc-sdk":false}},"/v1/oauth/delegated/authorize":{"post":{"description":"Returns the live effective-policy decision for a single `(action, resource)` pair. Evaluated per call against the grant’s policy AND the authorizing human’s current workspace policy — never from a decision cached at consent time. The delegated access token is presented as the bearer.","operationId":"OAuthDelegatedAuthorizationController_authorize","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegatedAuthorizationRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegatedAuthorizationResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing or malformed `Authorization` header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Decide one action for a delegated access token","tags":["oauth-authorization-server"],"x-pc-sdk":false}},"/v1/oauth/delegated/authorize-batch":{"post":{"description":"Evaluates a list of actions against the same live effective policy as `POST /authorize`, in one pass. Exists so an MCP server can filter a several-hundred-tool catalog down to what the session actually permits without a round trip per tool. It is a **listing** aid: a tool invocation is still decided on its own, per call.","operationId":"OAuthDelegatedAuthorizationController_authorizeBatch","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegatedAuthorizationBatchRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegatedAuthorizationBatchResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"Empty or oversized `actions` list.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Missing or malformed `Authorization` header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Decide many actions for a delegated access token","tags":["oauth-authorization-server"],"x-pc-sdk":false}},"/v1/oauth/delegated/downstream-assertion":{"post":{"description":"Exchanges a delegated access token for a ~60s assertion audienced at ONE named service, so that service can verify the caller offline without calling back (`docs/mcp.md` §5b). The assertion carries identity — account, workspace, client, grant — and deliberately no policy: the target resolves the delegated effective policy per request through `/v1/introspect`, so a revoked grant or a demoted human is refused on the next call rather than at this assertion’s expiry.","operationId":"OAuthDelegatedAuthorizationController_downstreamAssertion","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownstreamAssertionRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownstreamAssertionResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"400":{"description":"The requested `audience` is not a service we issue assertions for.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["BAD_REQUEST","VALIDATION_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Missing or malformed `Authorization` header, or the token/grant behind it is no longer live.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Mint a short-lived assertion for one downstream service","tags":["oauth-authorization-server"],"x-pc-sdk":false}},"/v1/oauth/delegated/authorize-assertion":{"post":{"description":"The REST-service counterpart of `POST /authorize`. A service holds only the short-lived assertion, never the delegated access token, so it asks here. Evaluated against the grant’s consented policy AND the authorizing human’s current workspace policy, live and uncached — a revoked grant, a demoted human or an offboarded one is refused on the next call.","operationId":"OAuthDelegatedAuthorizationController_authorizeAssertion","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssertionAuthorizationRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegatedAuthorizationResponseDto"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing or malformed `Authorization` header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Decide one action for a downstream assertion","tags":["oauth-authorization-server"],"x-pc-sdk":false}},"/v1/oauth/delegated/first-tool-call":{"post":{"description":"Called by the MCP server, best effort and off the call path, after the first tool call that succeeds on a connection. Stamps `first_tool_call_at` on the grant behind the presented access token once; later calls change nothing. The connections lists return the stamp, which is how the console shows a connection as working. Always 204 for a well-formed request, whether or not the token is live, so the route says nothing about token validity.","operationId":"OAuthDelegatedAuthorizationController_firstToolCall","parameters":[],"responses":{"204":{"description":"Recorded, or nothing to record.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"description":"Missing or malformed `Authorization` header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["UNAUTHORIZED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Rate limited: too many requests from this client IP in the last 60 seconds (`RATE_LIMITED`); wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (the window, 60).","schema":{"type":"integer","example":60}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"x-pc-error-codes":["RATE_LIMITED"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Record that a delegated connection made its first tool call","tags":["oauth-authorization-server"],"x-pc-sdk":false}}},"info":{"title":"Platform Auth API","description":"PlatformUser authentication and workspace administration for ProductCraft. Owns sign-in, sign-up, password reset, workspaces, members, invites, workspace roles, workspace-service toggles, and the introspect endpoint every other backend uses to resolve permissions.\n\n## Rate limits\n\nEvery route is limited per client IP over a sliding 60-second window: 10 requests for sign-in, sign-up, token refresh, sign-out, password reset, invite acceptance and OAuth client registration; 60 for the OAuth token endpoint; 600 for the MCP delegated authorization decision; 60 for everything else. Over the limit the response is `429` with code `RATE_LIMITED` and a `Retry-After` header in seconds. Sign-in also limits attempts per identifier (`TOO_MANY_ATTEMPTS`).","version":"1.0.0","contact":{}},"tags":[{"name":"OAuth Sign-In","description":"Sign in to ProductCraft with Google, GitHub or Apple (browser redirects; not part of the SDKs)."},{"name":"account","description":"Close the signed-in ProductCraft account."},{"name":"authentication","description":"Platform sign-up, sign-in, token refresh, sign-out and password reset for ProductCraft accounts (the people who run workspaces, not your end users: those sign in through Auth)."},{"name":"introspect","description":"Who is calling: the session, its membership and effective policy in a workspace, and what a workspace API key resolves to. Product APIs call these to authorise requests."},{"name":"jwks","description":"The public keys that verify platform-issued JWTs."},{"name":"me","description":"The signed-in account: profile, avatar and console guide preferences."},{"name":"oauth-authorization-server","description":"The OAuth 2.1 authorization server third-party clients (MCP assistants) connect through, and the apps connected to your account or workspace. The protocol endpoints (registration, token, revocation, introspection, consent, delegated decisions) are for OAuth clients and the MCP server, not the SDKs."},{"name":"platform-api-keys","description":"Workspace API keys (`pcft_live_…`): mint from a preset or managed policies, list, rotate, rebind, revoke, and ask a key what it can do (`api-keys/self`)."},{"name":"session","description":"The signed-in account's sessions: list them and sign out of one or all others."},{"name":"verification","description":"Verify the account email address with the emailed code, or send a new code."},{"name":"workspace-audit-logs","description":"The workspace audit log and the cross-product audit feed, with NDJSON or CSV export."},{"name":"workspace-policies","description":"Managed IAM-style policies that roles and API keys are bound to, and the action catalog they are written against."},{"name":"workspace-roles","description":"Custom and system roles in a workspace and the policy each grants."},{"name":"workspace-services","description":"Turn products (Auth, Mail, Waitlist, Social, Trawl, Flags, Notify) on or off for a workspace, with their settings."},{"name":"workspace-stats","description":"Workspace dashboard totals and a daily series of admin changes."},{"name":"workspaces","description":"Workspaces, their members and invites. Platform routes name a workspace by its slug, positionally (`workspaces.retrieve(\"acme\")`); the product APIs bind `workspace_id` instead."}],"servers":[{"url":"https://api.platform-auth.productcraft.co","description":"Platform Auth API"}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"SignUpDto":{"type":"object","properties":{"email":{"type":"string","description":"User email address","example":"user@example.com"},"username":{"type":"string","description":"Unique username (letters, numbers, dot, underscore, hyphen)","example":"john_doe"},"password":{"type":"string","description":"User password (min 8 characters)","example":"MySecurePassword123"},"display_name":{"type":"string","description":"Display name","example":"John Doe"},"session_duration":{"description":"Session duration: \"short\" (24h), \"long\" (90d), or integer seconds (3600–7776000). Defaults to 30 days.","oneOf":[{"type":"string","enum":["short","long"]},{"type":"integer","minimum":3600,"maximum":7776000}],"example":"long"}},"required":["email","username","password"]},"TokenResponseDto":{"type":"object","properties":{"access_token":{"type":"string","description":"Access token (JWT)","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"refresh_token":{"type":"string","description":"Refresh token (JWT)","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"token_type":{"type":"string","description":"Token type","example":"Bearer"},"expires_in":{"type":"number","description":"Access token TTL in seconds","example":3600}},"required":["access_token","token_type","expires_in"],"x-pc-sdk-model":"Token"},"MfaRequiredFlag":{"type":"number","enum":[true]},"MfaFactorType":{"type":"string","enum":["totp","email","webauthn"]},"MfaChallengeFactorDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Factor id; send it back as `factor_id`."},"type":{"description":"Kind of factor. Clients treat this as an open enum.","allOf":[{"$ref":"#/components/schemas/MfaFactorType"}]},"label":{"type":"string","description":"Name the account holder gave it (or a default)."},"email_masked":{"type":"string","description":"Email factors: the masked destination, e.g. `c***h@g***l.com`."}},"required":["id","type","label"],"x-pc-sdk-model":"MfaChallengeFactor"},"MfaChallengeResponseDto":{"type":"object","properties":{"mfa_required":{"description":"Always `true`: tell this apart from a token response by this field.","allOf":[{"$ref":"#/components/schemas/MfaRequiredFlag"}]},"mfa_token":{"type":"string","description":"Opaque, single use, valid 10 minutes, 5 wrong answers in total. Send it to `/v1/auth/mfa/*`."},"expires_at":{"type":"string","format":"date-time","description":"When `mfa_token` expires."},"factors":{"description":"The account's active factors.","type":"array","items":{"$ref":"#/components/schemas/MfaChallengeFactorDto"}},"recovery_codes_available":{"type":"boolean","description":"Whether an unused recovery code exists (offer \"use a recovery code\")."}},"required":["mfa_required","mfa_token","expires_at","factors","recovery_codes_available"],"x-pc-sdk-model":"MfaChallenge"},"SignInDto":{"type":"object","properties":{"identifier":{"type":"string","description":"Email or username","example":"user@example.com"},"password":{"type":"string","description":"User password","example":"MySecurePassword123"},"session_duration":{"description":"Session duration: \"short\" (24h), \"long\" (90d), or integer seconds (3600–7776000). Defaults to 30 days.","oneOf":[{"type":"string","enum":["short","long"]},{"type":"integer","minimum":3600,"maximum":7776000}],"example":"short"}},"required":["identifier","password"]},"RefreshDto":{"type":"object","properties":{"refresh_token":{"type":"string","description":"Refresh token (JWT)","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}},"required":["refresh_token"]},"LogoutDto":{"type":"object","properties":{"refresh_token":{"type":"string","description":"Refresh token (JWT)","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}},"required":["refresh_token"]},"RequestPasswordResetDto":{"type":"object","properties":{"email":{"type":"string","description":"Email address to send reset token","example":"user@example.com"}},"required":["email"]},"ErrorParamDto":{"type":"object","properties":{"param":{"type":"string","description":"Wire path of the invalid field: `email`, `items.0.display_name`.","example":"email"},"message":{"type":"string","description":"What is wrong with it; the same text as the field's entry in an array `message`.","example":"email must be an email"},"code":{"type":"string","description":"The failed rule (class-validator constraint name, e.g. `isEmail`, `isUuid`, `whitelistValidation` for a field the operation does not declare), or `invalid`.","example":"isEmail"}},"required":["param","message","code"]},"ErrorResponseDto":{"type":"object","properties":{"status_code":{"type":"number","description":"HTTP status code, same as the response status.","example":404},"statusCode":{"type":"number","description":"Deprecated alias of `status_code`, same value. Kept so existing clients keep working; read `status_code`. Error responses carry `Deprecation: true` while it is sent.","example":404,"deprecated":true},"message":{"description":"Human-readable error message. A string, or on a `VALIDATION_ERROR` an array with one message per invalid field (the same texts as `errors[].message`). Branch on `code`, not on this.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"example":"Domain not found"},"code":{"description":"Stable, machine-readable error code; branch on this, not on `message`. Always present. A route-specific code when the route defines one, otherwise the generic code for the status (`NOT_FOUND`, `VALIDATION_ERROR`, `RATE_LIMITED`, ...). Open set: accept codes you do not know. Each code is documented at https://productcraft.co/docs/errors#<code>.","example":"NOT_FOUND","allOf":[{"$ref":"#/components/schemas/PlatformErrorCode"}]},"request_id":{"type":"string","description":"The request's id, same as the `X-Request-Id` response header. Quote it when contacting support.","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","example":"req_6f1c2a9d4b7e4f0a8c3d2e1f0a9b8c7d"},"errors":{"description":"One entry per invalid request field on a `VALIDATION_ERROR`; empty on every other error.","type":"array","items":{"$ref":"#/components/schemas/ErrorParamDto"}},"details":{"type":"object","description":"Structured context for errors a client has to act on, keyed in snake_case and specific to the code (e.g. `{ fqdn, reason }` on `from_domain_not_verified`). Absent on most errors.","additionalProperties":true,"example":{"fqdn":"mail.example.com","reason":"not_verified"}}},"required":["status_code","message","code","request_id","errors"]},"ResetPasswordDto":{"type":"object","properties":{"token":{"type":"string","description":"6-digit reset token sent via email","example":"123456"},"new_password":{"type":"string","description":"New password (min 8 characters)","example":"MyNewPassword123"}},"required":["token","new_password"]},"MfaSendCodeDto":{"type":"object","properties":{"mfa_token":{"type":"string","description":"`mfa_token` from the sign-in answer.","maxLength":256},"factor_id":{"type":"string","format":"uuid","description":"The email factor to send to."}},"required":["mfa_token","factor_id"]},"CodeSentDto":{"type":"object","properties":{"destination_masked":{"type":"string","description":"Masked address the code went to."},"code_expires_at":{"type":"string","format":"date-time","description":"When the code stops working (5 minutes)."}},"required":["destination_masked","code_expires_at"],"x-pc-sdk-model":"CodeSent"},"MfaTokenDto":{"type":"object","properties":{"mfa_token":{"type":"string","description":"`mfa_token` from the sign-in answer.","maxLength":256}},"required":["mfa_token"]},"WebauthnRequestOptionsDto":{"type":"object","properties":{"public_key":{"type":"object","description":"`PublicKeyCredentialRequestOptions` (`challenge`, `rp_id`, `allow_credentials[]` with base64url ids, `user_verification`, `timeout`). Decode the base64url fields to ArrayBuffers and pass to `navigator.credentials.get({ publicKey })`.","additionalProperties":true}},"required":["public_key"]},"MfaVerifyDto":{"type":"object","properties":{"mfa_token":{"type":"string","description":"`mfa_token` from the sign-in answer.","maxLength":256},"factor_id":{"type":"string","format":"uuid","description":"The factor answered (TOTP, email or passkey). Omit with `recovery_code`."},"code":{"type":"string","description":"6-digit TOTP or email code.","pattern":"^\\d{6}$"},"recovery_code":{"type":"string","description":"A recovery code (`abcd-efgh-jk`, case-insensitive, dashes optional). Works once."},"webauthn":{"type":"object","description":"The `PublicKeyCredential` from `navigator.credentials.get()`, ArrayBuffers base64url-encoded: `{ id, raw_id, type: \"public-key\", response: { clientDataJSON, authenticatorData, signature, userHandle } }`. WebAuthn member names are passed through verbatim (camelCase by spec).","additionalProperties":true}},"required":["mfa_token"]},"StepUpMethod":{"type":"string","enum":["totp","email","webauthn","recovery_code","password","reauthenticate"]},"StepUpStatusDto":{"type":"object","properties":{"active":{"type":"boolean","description":"True while the session completed a second step (or signed in) in the last 10 minutes."},"valid_until":{"type":"string","format":"date-time","nullable":true,"description":"End of the current window, or null when not stepped up."},"methods":{"type":"array","description":"How this session can step up. Open enum.","items":{"$ref":"#/components/schemas/StepUpMethod"}},"factors":{"description":"The account's active factors to offer.","type":"array","items":{"$ref":"#/components/schemas/MfaChallengeFactorDto"}}},"required":["active","valid_until","methods","factors"],"x-pc-sdk-model":"StepUpStatus"},"StepUpSendCodeDto":{"type":"object","properties":{"factor_id":{"type":"string","format":"uuid","description":"The email factor to send to."}},"required":["factor_id"]},"StepUpVerifyDto":{"type":"object","properties":{"factor_id":{"type":"string","format":"uuid","description":"The factor answered (TOTP, email or passkey)."},"code":{"type":"string","description":"6-digit TOTP or email code.","pattern":"^\\d{6}$"},"recovery_code":{"type":"string","description":"A recovery code. Works once."},"webauthn":{"type":"object","description":"The `PublicKeyCredential` from `navigator.credentials.get()`, ArrayBuffers base64url-encoded: `{ id, raw_id, type: \"public-key\", response: { clientDataJSON, authenticatorData, signature, userHandle } }`. WebAuthn member names are passed through verbatim (camelCase by spec).","additionalProperties":true},"password":{"type":"string","description":"Only for an account WITHOUT factors: its password.","maxLength":1024}}},"StepUpResultDto":{"type":"object","properties":{"valid_until":{"type":"string","format":"date-time","description":"Sensitive actions are allowed until then."}},"required":["valid_until"],"x-pc-sdk-model":"StepUpResult"},"MfaFactorStatus":{"type":"string","enum":["active"]},"MfaFactorDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Factor id; send it back as `factor_id`."},"type":{"description":"Kind of factor. Clients treat this as an open enum.","allOf":[{"$ref":"#/components/schemas/MfaFactorType"}]},"label":{"type":"string","description":"Name the account holder gave it (or a default)."},"email_masked":{"type":"string","description":"Email factors: the masked destination, e.g. `c***h@g***l.com`."},"status":{"description":"Only active factors are listed.","allOf":[{"$ref":"#/components/schemas/MfaFactorStatus"}]},"created_at":{"type":"string","format":"date-time","description":"When the factor was turned on."},"last_used_at":{"type":"string","format":"date-time","nullable":true,"description":"Last time it completed a second step."}},"required":["id","type","label","status","created_at","last_used_at"],"x-pc-sdk-model":"MfaFactor"},"MfaRequiredByDto":{"type":"object","properties":{"workspace_id":{"type":"string","format":"uuid","description":"Id of the workspace that requires it."},"workspace_slug":{"type":"string","description":"Workspace slug."},"display_name":{"type":"string","description":"Workspace display name."},"deadline":{"type":"string","format":"date-time","nullable":true,"description":"When this member loses access without two-step sign-in: max(requirement turned on, joined) + grace period."},"blocked":{"type":"boolean","description":"True once the deadline passed without a factor: the workspace refuses this account (`MFA_ENROLLMENT_REQUIRED`)."}},"required":["workspace_id","workspace_slug","display_name","deadline","blocked"],"x-pc-sdk-model":"MfaRequiredBy"},"MfaOverviewDto":{"type":"object","properties":{"enabled":{"type":"boolean","description":"True when the account has at least one active factor."},"factors":{"description":"Active factors.","type":"array","items":{"$ref":"#/components/schemas/MfaFactorDto"}},"recovery_codes_remaining":{"type":"number","description":"Unused recovery codes."},"required_by":{"description":"Workspaces that require two-step sign-in of this account.","type":"array","items":{"$ref":"#/components/schemas/MfaRequiredByDto"}}},"required":["enabled","factors","recovery_codes_remaining","required_by"],"x-pc-sdk-model":"MfaOverview"},"StartFactorDto":{"type":"object","properties":{"label":{"type":"string","description":"Name for the factor (max 64).","maxLength":64}}},"TotpEnrollmentDto":{"type":"object","properties":{"factor_id":{"type":"string","format":"uuid","description":"The pending factor; confirm it with a code."},"secret":{"type":"string","description":"Base32 secret for manual entry. Shown once."},"otpauth_uri":{"type":"string","description":"`otpauth://` URI for authenticator apps."},"qr_data_url":{"type":"string","description":"PNG data URL of the QR code for `otpauth_uri`."}},"required":["factor_id","secret","otpauth_uri","qr_data_url"],"x-pc-sdk-model":"TotpEnrollment"},"ConfirmCodeDto":{"type":"object","properties":{"code":{"type":"string","description":"The 6-digit code from the app or the email.","pattern":"^\\d{6}$"}},"required":["code"]},"FactorActivatedDto":{"type":"object","properties":{"factor":{"$ref":"#/components/schemas/MfaFactorDto"},"recovery_codes":{"description":"Only when this was the account's FIRST factor: 10 single-use recovery codes, returned exactly once.","type":"array","items":{"type":"string"}}},"required":["factor"],"x-pc-sdk-model":"FactorActivated"},"EmailEnrollmentDto":{"type":"object","properties":{"destination_masked":{"type":"string","description":"Masked address the code went to."},"code_expires_at":{"type":"string","format":"date-time","description":"When the code stops working (5 minutes)."},"factor_id":{"type":"string","format":"uuid","description":"The pending factor; confirm it with the emailed code."}},"required":["destination_masked","code_expires_at","factor_id"],"x-pc-sdk-model":"EmailEnrollment"},"WebauthnEnrollmentDto":{"type":"object","properties":{"factor_id":{"type":"string","format":"uuid","description":"The pending factor; confirm it with the created credential."},"public_key":{"type":"object","description":"`PublicKeyCredentialCreationOptions` (rp `productcraft.co`) for `navigator.credentials.create({ publicKey })` after decoding base64url fields (`challenge`, `user.id`, `exclude_credentials[].id`).","additionalProperties":true}},"required":["factor_id","public_key"]},"ConfirmWebauthnDto":{"type":"object","properties":{"credential":{"type":"object","description":"The `PublicKeyCredential` from `navigator.credentials.create()`, ArrayBuffers base64url-encoded: `{ id, raw_id, type, response: { clientDataJSON, attestationObject, transports? } }` (member names verbatim).","additionalProperties":true}},"required":["credential"]},"RenameFactorDto":{"type":"object","properties":{"label":{"type":"string","description":"New name (1-64).","minLength":1,"maxLength":64}},"required":["label"]},"RecoveryCodesDto":{"type":"object","properties":{"recovery_codes":{"description":"The new recovery codes (every previous code stops working). Shown once.","type":"array","items":{"type":"string"}}},"required":["recovery_codes"],"x-pc-sdk-model":"RecoveryCodes"},"CallbackBodyDto":{"type":"object","properties":{"state":{"type":"string","description":"Opaque state token returned by the IdP, minted at `/start`. Single-use; binds the callback to a specific browser session.","maxLength":512},"id_token":{"type":"string","description":"JWT id_token from the IdP (OIDC providers; Apple form_post). Optional — either `idToken` or `code` must be supplied.","maxLength":8192},"code":{"type":"string","description":"OAuth authorization code returned by the IdP. Optional — either `idToken` or `code` must be supplied.","maxLength":2048},"user":{"type":"string","description":"Apple-only first-signin payload: JSON-encoded `{ name, email }`. Apple returns this only the first time a user signs in. Not signed — treated as untrusted input by the controller's payload parser.","maxLength":4096}},"required":["state"]},"OAuthCallbackResultDto":{"type":"object","properties":{"tokens":{"description":"Issued PlatformUser session tokens. auth-ui sets the auth_token cookie from `accessToken` and 302s the browser to `return_to`. Absent when the account has two-step sign-in on (see `mfa`).","allOf":[{"$ref":"#/components/schemas/TokenResponseDto"}]},"mfa":{"description":"Present instead of `tokens` when the account has two-step sign-in on: the same challenge `POST /v1/auth/signin` returns. Finish with `POST /v1/auth/mfa/verify`, then redirect to `return_to`.","allOf":[{"$ref":"#/components/schemas/MfaChallengeResponseDto"}]},"return_to":{"type":"string","description":"Original `return_to` the user was sent off with. auth-ui redirects here after writing the cookie."}},"required":["return_to"]},"IntrospectPrincipalDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the authenticated account.","format":"uuid"},"sub":{"type":"string","description":"JWT subject: the account id.","format":"uuid"},"email":{"type":"string","description":"The account's primary email, when it has one.","nullable":true},"name":{"type":"string","description":"The account's display name, when set.","nullable":true}},"required":["id","sub","email","name"],"x-pc-sdk-model":"IntrospectPrincipal"},"IntrospectAccountDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the account.","format":"uuid"},"email":{"type":"string","description":"Primary email of the account, when it has one.","nullable":true},"username":{"type":"string","description":"Unique username of the account."},"display_name":{"type":"string","description":"Display name, when set.","nullable":true},"status":{"type":"string","description":"Account status (e.g. `active`, `suspended`)."},"email_verified_at":{"type":"string","nullable":true,"format":"date-time","description":"Timestamp when this account verified its primary email, or null if unverified."},"avatar_url":{"type":"string","nullable":true,"description":"Public HTTPS URL of the uploaded avatar, or null when no avatar is set."}},"required":["id","email","username","display_name","status","email_verified_at","avatar_url"],"x-pc-sdk-model":"IntrospectAccount"},"IntrospectWorkspaceListItemDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the workspace.","format":"uuid"},"slug":{"type":"string","description":"Slug of the workspace (platform routes take it positionally)."},"display_name":{"type":"string","description":"Display name of the workspace."},"role":{"type":"string","description":"Caller’s role name in this workspace.","example":"owner"},"services":{"description":"Enabled services on this workspace.","example":["mail","waitlist"],"type":"array","items":{"type":"string"}},"avatar_url":{"type":"string","nullable":true,"description":"Workspace identity avatar (public HTTPS URL), or null when none is set. Console workspace switcher reads this."}},"required":["id","slug","display_name","role","services","avatar_url"],"x-pc-sdk-model":"IntrospectWorkspaceListItem"},"IntrospectResponseDto":{"type":"object","properties":{"is_authenticated":{"type":"boolean","description":"False for an anonymous caller and for an access token whose session has been signed out."},"principal":{"description":"The authenticated caller, or `null` when the request carries no valid session.","nullable":true,"allOf":[{"$ref":"#/components/schemas/IntrospectPrincipalDto"}]},"account":{"description":"The caller's account profile, or `null` when not authenticated.","nullable":true,"allOf":[{"$ref":"#/components/schemas/IntrospectAccountDto"}]},"workspaces":{"description":"Workspaces the caller is a member of (empty when not authenticated).","type":"array","items":{"$ref":"#/components/schemas/IntrospectWorkspaceListItemDto"}}},"required":["is_authenticated"],"x-pc-sdk-model":"Introspect"},"IntrospectRoleDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the role (the key's workspace id for a workspace key).","format":"uuid"},"name":{"type":"string","description":"Name of the role (`owner`, `admin`, `member`, a custom role, or `pak`)."}},"required":["id","name"],"x-pc-sdk-model":"IntrospectRole"},"PolicyEffect":{"type":"string","enum":["allow","deny"]},"PolicyStatementDto":{"type":"object","properties":{"effect":{"description":"Whether the statement allows or denies the listed actions on the listed resources.","example":"allow","allOf":[{"$ref":"#/components/schemas/PolicyEffect"}]},"actions":{"description":"Action strings the statement applies to. Wildcards (e.g. `social.*`, `*.read`, `*`) supported per `actionMatches` semantics.","example":["social.read","social.list"],"minItems":1,"type":"array","items":{"type":"string"}},"resources":{"description":"Resource URNs the statement applies to. Use `[\"*\"]` for workspace-wide. Per-resource scoping (e.g. `pcft:agora:community/<uuid>`) is supported by the PAK lane today; custom roles accept only `[\"*\"]` for now.","example":["*"],"minItems":1,"type":"array","items":{"type":"string"}}},"required":["effect","actions","resources"],"x-pc-sdk-model":"PolicyStatement"},"IntrospectWorkspaceMfaDto":{"type":"object","properties":{"required":{"type":"boolean","description":"Whether the workspace requires two-step sign-in."},"enrolled":{"type":"boolean","description":"Whether the caller has an active two-step factor."},"deadline":{"type":"string","format":"date-time","nullable":true,"description":"When an unenrolled member loses access: max(requirement on, joined) + grace period. Null when not required."},"blocked":{"type":"boolean","description":"Past the deadline without a factor: `policy` is empty and platform routes answer `MFA_ENROLLMENT_REQUIRED`."}},"required":["required","enrolled","deadline","blocked"],"x-pc-sdk-model":"IntrospectWorkspaceMfa"},"IntrospectWorkspaceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Canonical workspace UUID. Only present for members — non-members get a uniform low-information response.","format":"uuid"},"is_member":{"type":"boolean","description":"Whether the caller is a member of the workspace (a workspace key bound to it counts as one). Non-members get no `id`, no role and an empty policy."},"role":{"description":"The caller's role in the workspace (`{ id, name: 'pak' }` for a workspace key), or `null` for a non-member.","nullable":true,"allOf":[{"$ref":"#/components/schemas/IntrospectRoleDto"}]},"policy":{"description":"Effective IAM-style policy for this caller in this workspace.","type":"array","items":{"$ref":"#/components/schemas/PolicyStatementDto"}},"services":{"description":"Enabled services on this workspace.","example":["mail","waitlist"],"type":"array","items":{"type":"string"}},"mfa":{"description":"Members only (not workspace keys): the workspace's two-step sign-in requirement for this caller (internal_docs/platform/mfa.md).","allOf":[{"$ref":"#/components/schemas/IntrospectWorkspaceMfaDto"}]}},"required":["is_member","role","policy","services"],"x-pc-sdk-model":"IntrospectWorkspace"},"IntrospectApiKeyResponseDto":{"type":"object","properties":{"is_valid":{"type":"boolean","description":"Always `true` on a 200: unknown, revoked and expired keys answer 401."},"workspace_id":{"type":"string","description":"Id of the workspace the key belongs to.","format":"uuid"},"policy":{"description":"Merged effective policy across every managed policy bound to this PAK.","type":"array","items":{"$ref":"#/components/schemas/PolicyStatementDto"}},"created_by":{"type":"string","description":"Account id of the person who minted the key, or `null` when that account is gone.","nullable":true,"format":"uuid"},"api_key_id":{"type":"string","description":"Id of the key.","format":"uuid"}},"required":["is_valid","workspace_id","policy","created_by","api_key_id"],"x-pc-sdk-model":"IntrospectApiKey"},"CreateWorkspaceDto":{"type":"object","properties":{"slug":{"type":"string","description":"URL-friendly slug. Lowercase alphanumerics, separated by hyphens. Used in URLs and as a stable handle.","example":"acme-corp","minLength":2,"maxLength":64},"display_name":{"type":"string","description":"Display name shown in console and on receipts.","example":"Acme Corp","minLength":1,"maxLength":128}},"required":["slug","display_name"]},"WorkspaceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the workspace.","format":"uuid"},"slug":{"type":"string","description":"Unique URL-friendly slug; platform routes take it positionally.","example":"acme-corp"},"display_name":{"type":"string","description":"Display name of the workspace.","example":"Acme Corp"},"created_by":{"type":"string","description":"Account id of the member who created the workspace, or `null` once that account has been deleted.","format":"uuid","nullable":true},"status":{"type":"string","description":"Workspace status (e.g. `active`).","example":"active"},"settings":{"type":"object","additionalProperties":true,"description":"Free-form workspace settings blob."},"created_at":{"type":"string","description":"When the workspace was created.","format":"date-time"},"updated_at":{"type":"string","description":"When the workspace was last changed.","format":"date-time"}},"required":["id","slug","display_name","created_by","status","settings","created_at","updated_at"],"x-pc-sdk-model":"Workspace"},"WorkspaceListItemDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the workspace.","format":"uuid"},"slug":{"type":"string","description":"Unique URL-friendly slug; platform routes take it positionally.","example":"acme-corp"},"display_name":{"type":"string","description":"Display name of the workspace.","example":"Acme Corp"},"created_by":{"type":"string","description":"Account id of the member who created the workspace, or `null` once that account has been deleted.","format":"uuid","nullable":true},"status":{"type":"string","description":"Workspace status (e.g. `active`).","example":"active"},"settings":{"type":"object","additionalProperties":true,"description":"Free-form workspace settings blob."},"created_at":{"type":"string","description":"When the workspace was created.","format":"date-time"},"updated_at":{"type":"string","description":"When the workspace was last changed.","format":"date-time"},"member_role_id":{"type":"string","nullable":true,"format":"uuid","description":"Caller’s workspace_role.id for this workspace."},"member_role":{"type":"string","nullable":true,"description":"Caller’s role name in this workspace.","example":"owner"}},"required":["id","slug","display_name","created_by","status","settings","created_at","updated_at","member_role_id","member_role"],"x-pc-sdk-model":"WorkspaceListItem"},"PaginationDto":{"type":"object","properties":{"next_cursor":{"type":"string","description":"Pass as `cursor` to get the next page; `null` on the last page.","nullable":true,"example":null},"has_more":{"type":"boolean","description":"Whether another page follows this one.","example":false}},"required":["next_cursor","has_more"],"x-pc-sdk-model":"Pagination"},"ListWorkspacesResponseDto":{"type":"object","properties":{"data":{"description":"One page of workspaces the caller belongs to.","type":"array","items":{"$ref":"#/components/schemas/WorkspaceListItemDto"}},"pagination":{"$ref":"#/components/schemas/PaginationDto"}},"required":["data","pagination"],"x-pc-sdk-model":"ListWorkspaces"},"UpdateWorkspaceDto":{"type":"object","properties":{"display_name":{"type":"string","description":"New display name of the workspace.","minLength":1,"maxLength":128,"example":"Acme Corp"},"slug":{"type":"string","description":"New URL-friendly slug. Same constraints as the create form. Renames are broadcast on the workspace events queue so denormalised consumers (waitlist-api, future product surfaces) can sync. Old URLs continue to resolve for one rename cycle.","minLength":2,"maxLength":64,"example":"acme"},"settings":{"type":"object","additionalProperties":true,"description":"Free-form workspace settings blob."}}},"WorkspaceAvatarUrlResponseDto":{"type":"object","properties":{"avatar_url":{"type":"string","description":"URL of the uploaded avatar image."}},"required":["avatar_url"],"x-pc-sdk-model":"WorkspaceAvatarUrl"},"WorkspaceMemberResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the membership.","format":"uuid"},"account_id":{"type":"string","description":"Id of the member's account.","format":"uuid"},"username":{"type":"string","description":"The member's username."},"display_name":{"type":"string","description":"The member's display name, when set.","nullable":true},"primary_email":{"type":"string","description":"The member's primary email, when it has one.","nullable":true},"avatar_url":{"type":"string","nullable":true,"description":"Presigned URL for the member's uploaded avatar, or null when they have none. Short-lived — mint a fresh one by re-reading this endpoint rather than caching the URL."},"role_id":{"type":"string","description":"Id of the member's role in this workspace.","format":"uuid"},"role":{"type":"string","description":"Name of the member's role."},"role_is_system":{"type":"boolean","description":"Whether the role is a system role (`owner`, `admin`, `member`) rather than a custom one."},"joined_at":{"type":"string","description":"When the member joined the workspace.","format":"date-time"}},"required":["id","account_id","username","display_name","primary_email","avatar_url","role_id","role","role_is_system","joined_at"],"x-pc-sdk-model":"WorkspaceMember"},"ListWorkspaceMembersResponseDto":{"type":"object","properties":{"data":{"description":"One page of workspace members.","type":"array","items":{"$ref":"#/components/schemas/WorkspaceMemberResponseDto"}},"pagination":{"$ref":"#/components/schemas/PaginationDto"}},"required":["data","pagination"],"x-pc-sdk-model":"ListWorkspaceMembers"},"UpdateMemberRoleDto":{"type":"object","properties":{"role_id":{"type":"string","description":"UUID of the role to assign. Use this to target custom roles.","example":"11111111-1111-4111-8111-111111111111"},"role":{"type":"string","description":"System role shortcut: 'owner' | 'admin' | 'member'. Either `roleId` or `role` must be supplied.","enum":["owner","admin","member"]}}},"UpdateMemberRoleResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the membership.","format":"uuid"},"workspace_id":{"type":"string","description":"Id of the workspace.","format":"uuid"},"account_id":{"type":"string","description":"Id of the member's account.","format":"uuid"},"role_id":{"type":"string","description":"Id of the member's new role.","format":"uuid"},"invited_by":{"type":"string","description":"Account id of the member who invited them, when they joined by invite.","nullable":true,"format":"uuid"},"joined_at":{"type":"string","description":"When the member joined the workspace.","format":"date-time"}},"required":["id","workspace_id","account_id","role_id","invited_by","joined_at"],"x-pc-sdk-model":"UpdateMemberRole"},"AcceptWorkspaceInviteDto":{"type":"object","properties":{"code":{"type":"string","description":"Invite code from the invite email / link.","example":"inv_…"}},"required":["code"]},"CreateWorkspaceInviteDto":{"type":"object","properties":{"email":{"type":"string","description":"Optional invitee email. When set, the invite is locked to that address.","example":"alice@example.com"},"role_id":{"type":"string","description":"UUID of the role to grant on accept. Use to target custom roles.","example":"11111111-1111-1111-1111-111111111111"},"role":{"type":"string","description":"System role shortcut: 'owner' | 'admin' | 'member'.","enum":["owner","admin","member"]},"max_uses":{"type":"number","description":"Maximum number of accepts. Defaults to 1. Use higher values for \"team link\" invites.","example":1,"minimum":1,"maximum":10000},"expires_in_hours":{"type":"number","description":"Hours until the invite expires. Defaults to 168 (7 days).","example":168,"minimum":1,"maximum":8760}}},"WorkspaceInviteResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the invite.","format":"uuid"},"workspace_id":{"type":"string","description":"Id of the workspace the invite joins.","format":"uuid"},"code":{"type":"string","description":"Single-use invite code embedded in the invite URL."},"email":{"type":"string","description":"Email the invite is restricted to, or `null` for an open invite link.","nullable":true,"format":"email"},"role_id":{"type":"string","description":"Id of the role the invitee gets, or `null` for the default member role.","nullable":true,"format":"uuid"},"max_uses":{"type":"number","description":"How many times the invite can be accepted, or `null` for unlimited.","nullable":true},"use_count":{"type":"number","description":"How many times the invite has been accepted."},"expires_at":{"type":"string","description":"When the invite stops working, or `null` if it never expires.","nullable":true,"format":"date-time"},"revoked_at":{"type":"string","description":"When the invite was revoked, or `null` while it is live.","nullable":true,"format":"date-time"},"created_at":{"type":"string","description":"When the invite was created.","format":"date-time"},"created_by":{"type":"string","description":"Account id of the member who created the invite, or `null` once that account has been deleted.","format":"uuid","nullable":true}},"required":["id","workspace_id","code","email","role_id","max_uses","use_count","expires_at","revoked_at","created_at","created_by"],"x-pc-sdk-model":"WorkspaceInvite"},"WorkspaceInviteListItemDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the invite.","format":"uuid"},"workspace_id":{"type":"string","description":"Id of the workspace the invite joins.","format":"uuid"},"code":{"type":"string","description":"Single-use invite code embedded in the invite URL."},"email":{"type":"string","description":"Email the invite is restricted to, or `null` for an open invite link.","nullable":true,"format":"email"},"role_id":{"type":"string","description":"Id of the role the invitee gets, or `null` for the default member role.","nullable":true,"format":"uuid"},"max_uses":{"type":"number","description":"How many times the invite can be accepted, or `null` for unlimited.","nullable":true},"use_count":{"type":"number","description":"How many times the invite has been accepted."},"expires_at":{"type":"string","description":"When the invite stops working, or `null` if it never expires.","nullable":true,"format":"date-time"},"revoked_at":{"type":"string","description":"When the invite was revoked, or `null` while it is live.","nullable":true,"format":"date-time"},"created_at":{"type":"string","description":"When the invite was created.","format":"date-time"},"created_by":{"type":"string","description":"Account id of the member who created the invite, or `null` once that account has been deleted.","format":"uuid","nullable":true},"role_name":{"type":"string","description":"Name of the role the invitee gets, or `null` for the default member role.","nullable":true}},"required":["id","workspace_id","code","email","role_id","max_uses","use_count","expires_at","revoked_at","created_at","created_by","role_name"],"x-pc-sdk-model":"WorkspaceInviteListItem"},"ListWorkspaceInvitesResponseDto":{"type":"object","properties":{"data":{"description":"One page of invites.","type":"array","items":{"$ref":"#/components/schemas/WorkspaceInviteListItemDto"}},"pagination":{"$ref":"#/components/schemas/PaginationDto"}},"required":["data","pagination"],"x-pc-sdk-model":"ListWorkspaceInvites"},"WorkspaceSecurityMemberDto":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"Member account id."},"username":{"type":"string","description":"Member username."},"display_name":{"type":"string","nullable":true,"description":"Member display name."},"email":{"type":"string","nullable":true,"format":"email","description":"Member primary email."},"mfa_enabled":{"type":"boolean","description":"Has at least one active factor."},"deadline":{"type":"string","format":"date-time","nullable":true,"description":"When this member loses access without two-step sign-in; null when not required."},"blocked":{"type":"boolean","description":"Past the deadline without two-step sign-in: the workspace refuses this member."}},"required":["account_id","username","display_name","email","mfa_enabled","deadline","blocked"],"x-pc-sdk-model":"WorkspaceSecurityMember"},"WorkspaceSecurityDto":{"type":"object","properties":{"mfa_required":{"type":"boolean","description":"Whether members must use two-step sign-in."},"mfa_required_since":{"type":"string","format":"date-time","nullable":true,"description":"When the requirement was turned on."},"grace_period_days":{"type":"number","minimum":0,"maximum":30,"description":"Days a member has to turn it on."},"members":{"description":"Per-member status; only for callers holding `workspace.member.read`.","type":"array","items":{"$ref":"#/components/schemas/WorkspaceSecurityMemberDto"}}},"required":["mfa_required","mfa_required_since","grace_period_days"],"x-pc-sdk-model":"WorkspaceSecurity"},"UpdateWorkspaceSecurityDto":{"type":"object","properties":{"mfa_required":{"type":"boolean","description":"Require two-step sign-in of every member."},"grace_period_days":{"type":"number","minimum":0,"maximum":30,"default":7,"description":"Days members get to turn it on (0-30)."}},"required":["mfa_required"]},"WorkspaceRoleResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the role.","format":"uuid"},"name":{"type":"string","description":"Role name. System role names are `owner`/`admin`/`member`."},"description":{"type":"string","description":"What the role is for, when set.","nullable":true},"is_system":{"type":"boolean","description":"True for built-in system roles (owner/admin/member); false for custom roles."},"policy":{"description":"Effective IAM-style policy. When `policy_id` is set this is the bound managed policy; otherwise it is the inline policy column.","type":"array","items":{"$ref":"#/components/schemas/PolicyStatementDto"}},"policy_id":{"type":"string","nullable":true,"format":"uuid","description":"Managed policy ID if the role is bound to one, else null."}},"required":["id","name","description","is_system","policy","policy_id"],"x-pc-sdk-model":"WorkspaceRole"},"ListWorkspaceRolesResponseDto":{"type":"object","properties":{"data":{"description":"One page of roles.","type":"array","items":{"$ref":"#/components/schemas/WorkspaceRoleResponseDto"}},"pagination":{"$ref":"#/components/schemas/PaginationDto"}},"required":["data","pagination"],"x-pc-sdk-model":"ListWorkspaceRoles"},"CreateWorkspaceRoleDto":{"type":"object","properties":{"name":{"type":"string","description":"Role name. Free-form; not URL-significant.","example":"BillingAdmin","minLength":1,"maxLength":64},"description":{"type":"string","description":"Optional human-readable role description.","example":"Manages billing and reads invoices.","maxLength":256},"policy":{"description":"IAM-style policy granting the role its permissions. Same wire shape as PAK policies. Omit or pass `[]` for a no-permissions role.","example":[{"effect":"allow","actions":["mail.*.read"],"resources":["*"]}],"type":"array","items":{"$ref":"#/components/schemas/PolicyStatementDto"}},"policy_id":{"type":"string","description":"Optional managed-policy id to bind the role to. When set, the role's effective policy comes from the bound managed policy and `policy` (inline) must be omitted.","nullable":true,"example":"11111111-1111-1111-1111-111111111111"}},"required":["name"]},"UpdateWorkspaceRoleDto":{"type":"object","properties":{"name":{"type":"string","description":"New name of the role.","minLength":1,"maxLength":64,"example":"BillingAdmin"},"description":{"type":"string","description":"New description of the role.","maxLength":256,"example":"Manages billing and reads invoices."},"policy":{"description":"Replaces the role policy if provided. Omit to leave policy unchanged.","example":[{"effect":"allow","actions":["mail.*.read"],"resources":["*"]}],"type":"array","items":{"$ref":"#/components/schemas/PolicyStatementDto"}},"policy_id":{"type":"string","description":"Bind / unbind the role to a managed policy. UUID → bind, null → unbind, omit → leave unchanged.","nullable":true,"example":"11111111-1111-1111-1111-111111111111"}}},"ApiKeyPresetKey":{"type":"string","enum":["mail-send","waitlist-write","trawl-jobs","flags","flags-dev","notify-send","notify-readonly","readonly","full"]},"ManagedPolicyResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the policy.","format":"uuid"},"workspace_id":{"type":"string","description":"Id of the workspace that owns the policy.","format":"uuid"},"name":{"type":"string","description":"Name of the policy, unique in the workspace.","example":"mail-readonly"},"description":{"type":"string","description":"What the policy is for, when set.","nullable":true},"policy":{"description":"IAM-style policy statements bound to this managed policy.","type":"array","items":{"$ref":"#/components/schemas/PolicyStatementDto"}},"preset_key":{"nullable":true,"example":"mail-send","description":"The workspace-key preset this policy was created from, or null for a policy a person wrote. Minting a key with `preset` creates this policy once per workspace and reuses it. It stays set after the policy is edited, so show it as \"based on preset\".","allOf":[{"$ref":"#/components/schemas/ApiKeyPresetKey"}]},"created_by":{"type":"string","nullable":true,"format":"uuid","description":"Account that authored the row. Only revealed to callers with `workspace.audit.read`; plain members see null."},"created_at":{"type":"string","description":"When the policy was created.","format":"date-time"},"updated_at":{"type":"string","description":"When the policy was last changed.","format":"date-time"}},"required":["id","workspace_id","name","description","policy","preset_key","created_by","created_at","updated_at"],"x-pc-sdk-model":"ManagedPolicy"},"ListManagedPoliciesResponseDto":{"type":"object","properties":{"data":{"description":"One page of managed policies.","type":"array","items":{"$ref":"#/components/schemas/ManagedPolicyResponseDto"}},"pagination":{"$ref":"#/components/schemas/PaginationDto"}},"required":["data","pagination"],"x-pc-sdk-model":"ListManagedPolicies"},"WorkspaceActionCatalogResponseDto":{"type":"object","properties":{"actions":{"description":"Every known workspace action across all enabled service catalogs.","type":"array","items":{"type":"string"}}},"required":["actions"],"x-pc-sdk-model":"WorkspaceActionCatalog"},"PolicyBindingCountDto":{"type":"object","properties":{"pak":{"type":"number","description":"Number of platform API keys bound to this policy."},"role":{"type":"number","description":"Number of workspace roles bound to this policy."}},"required":["pak","role"],"x-pc-sdk-model":"PolicyBindingCount"},"ManagedPolicyDetailResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the policy.","format":"uuid"},"workspace_id":{"type":"string","description":"Id of the workspace that owns the policy.","format":"uuid"},"name":{"type":"string","description":"Name of the policy, unique in the workspace.","example":"mail-readonly"},"description":{"type":"string","description":"What the policy is for, when set.","nullable":true},"policy":{"description":"IAM-style policy statements bound to this managed policy.","type":"array","items":{"$ref":"#/components/schemas/PolicyStatementDto"}},"preset_key":{"nullable":true,"example":"mail-send","description":"The workspace-key preset this policy was created from, or null for a policy a person wrote. Minting a key with `preset` creates this policy once per workspace and reuses it. It stays set after the policy is edited, so show it as \"based on preset\".","allOf":[{"$ref":"#/components/schemas/ApiKeyPresetKey"}]},"created_by":{"type":"string","nullable":true,"format":"uuid","description":"Account that authored the row. Only revealed to callers with `workspace.audit.read`; plain members see null."},"created_at":{"type":"string","description":"When the policy was created.","format":"date-time"},"updated_at":{"type":"string","description":"When the policy was last changed.","format":"date-time"},"binding_count":{"description":"Counts of currently-bound consumers — surface this in delete-confirm UX so the operator sees cascade impact.","allOf":[{"$ref":"#/components/schemas/PolicyBindingCountDto"}]},"bound_key_count":{"type":"number","minimum":0,"example":3,"description":"Live (not revoked, not expired) API keys bound to this policy — the keys a save or delete affects. Show it in the confirm step before saving or deleting."}},"required":["id","workspace_id","name","description","policy","preset_key","created_by","created_at","updated_at","binding_count","bound_key_count"],"x-pc-sdk-model":"ManagedPolicyDetail"},"CreateWorkspacePolicyDto":{"type":"object","properties":{"name":{"type":"string","description":"Policy name (1-64 chars, alphanumeric + space/underscore/hyphen). Unique per workspace.","example":"mail-readonly","minLength":1,"maxLength":64},"description":{"type":"string","description":"Optional human description. Pass `null` to clear an existing description on PATCH.","nullable":true,"example":"Read-only access to all Mail resources"},"policy":{"description":"IAM-style policy. Empty array means \"no permissions\" — useful as a placeholder before granting any actions.","example":[{"effect":"allow","actions":["mail.read","mail.list"],"resources":["*"]}],"type":"array","items":{"$ref":"#/components/schemas/PolicyStatementDto"}}},"required":["name","policy"]},"UpdateWorkspacePolicyDto":{"type":"object","properties":{"name":{"type":"string","description":"Policy name (1-64 chars, alphanumeric + space/underscore/hyphen). Unique per workspace.","example":"mail-readonly","minLength":1,"maxLength":64},"description":{"type":"string","description":"Optional human description. Pass `null` to clear an existing description on PATCH.","nullable":true,"example":"Read-only access to all Mail resources"},"policy":{"description":"IAM-style policy. Empty array means \"no permissions\" — useful as a placeholder before granting any actions.","example":[{"effect":"allow","actions":["mail.read","mail.list"],"resources":["*"]}],"type":"array","items":{"$ref":"#/components/schemas/PolicyStatementDto"}}}},"ManagedPolicyDeletedResponseDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The deleted policy."},"deleted":{"type":"boolean","example":true,"description":"Always `true`: the policy is gone."},"bound_key_count":{"type":"number","minimum":0,"example":3,"description":"Live API keys that were bound to the policy and lost the binding. A key with no binding left falls back to deny-all."}},"required":["id","deleted","bound_key_count"],"x-pc-sdk-model":"ManagedPolicyDeleted"},"WorkspaceServiceStateDto":{"type":"object","properties":{"workspace_id":{"type":"string","description":"Id of the workspace.","format":"uuid"},"service":{"type":"string","description":"Service identifier (e.g. `mail`, `waitlist`, `social`, `auth`, `trawl`, `flags`, `notify`).","example":"mail"},"enabled":{"type":"boolean","description":"Whether the service is on for the workspace."},"enabled_at":{"type":"string","description":"When the service was last turned on, or `null` if never.","nullable":true,"format":"date-time"},"enabled_by":{"type":"string","description":"Account id of who last turned it on, or `null`.","nullable":true,"format":"uuid"},"disabled_at":{"type":"string","description":"When the service was last turned off, or `null`.","nullable":true,"format":"date-time"},"disabled_by":{"type":"string","description":"Account id of who last turned it off, or `null`.","nullable":true,"format":"uuid"},"settings":{"type":"object","additionalProperties":true,"description":"Per-service settings blob (service-specific shape)."},"prelaunch":{"type":"boolean","description":"Whether the product is in preview (pre-launch): it is not turned on for new workspaces automatically, and the console badges it \"Preview\".","example":false}},"required":["workspace_id","service","enabled","enabled_at","enabled_by","disabled_at","disabled_by","settings","prelaunch"],"x-pc-sdk-model":"WorkspaceServiceState"},"ListWorkspaceServicesResponseDto":{"type":"object","properties":{"data":{"description":"Every product service and its state in this workspace.","type":"array","items":{"$ref":"#/components/schemas/WorkspaceServiceStateDto"}}},"required":["data"],"x-pc-sdk-model":"ListWorkspaceServices"},"EnableWorkspaceServiceDto":{"type":"object","properties":{"settings":{"type":"object","additionalProperties":true,"description":"Optional per-service settings blob captured at enable time."}}},"BoundPolicySummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the policy.","format":"uuid"},"name":{"type":"string","description":"Name of the policy.","example":"mail-readonly"},"description":{"type":"string","description":"What the policy is for, when set.","nullable":true}},"required":["id","name","description"],"x-pc-sdk-model":"BoundPolicySummary"},"ApiKeyStatus":{"type":"string","enum":["active","expired","revoked"]},"PublicApiKeyDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the key.","format":"uuid"},"workspace_id":{"type":"string","description":"Id of the workspace the key belongs to.","format":"uuid"},"created_by":{"type":"string","description":"Account id of who minted the key, or `null` when that account is gone.","nullable":true,"format":"uuid"},"name":{"type":"string","description":"Name of the key."},"description":{"type":"string","description":"What the key is for, when set.","nullable":true},"token_prefix":{"type":"string","description":"The first ~14 chars of the token (prefix). Plaintext token is never returned after mint.","example":"pcft_live_abc123"},"policies":{"description":"Managed policies currently bound to this PAK.","type":"array","items":{"$ref":"#/components/schemas/BoundPolicySummaryDto"}},"last_used_at":{"type":"string","description":"When the key last authenticated a request, or `null` if never.","nullable":true,"format":"date-time"},"revoked_at":{"type":"string","description":"When the key was revoked, or `null` while it is not.","nullable":true,"format":"date-time"},"expires_at":{"type":"string","nullable":true,"format":"date-time","description":"When this key stops introspecting. `null` means it never expires."},"rotated_from":{"type":"string","nullable":true,"format":"uuid","description":"Id of the key this one replaced, when it was minted by a rotation."},"status":{"description":"Lifecycle state at the time of the request. Only `active` keys introspect. `revoked` beats `expired` — revocation is a deliberate act by a named actor and the row keeps saying so.","allOf":[{"$ref":"#/components/schemas/ApiKeyStatus"}]},"created_at":{"type":"string","description":"When the key was minted.","format":"date-time"},"updated_at":{"type":"string","description":"When the key was last changed.","format":"date-time"}},"required":["id","workspace_id","created_by","name","description","token_prefix","policies","last_used_at","revoked_at","expires_at","rotated_from","status","created_at","updated_at"],"x-pc-sdk-model":"PublicApiKey"},"ListPlatformApiKeysResponseDto":{"type":"object","properties":{"data":{"description":"One page of API keys, newest first.","type":"array","items":{"$ref":"#/components/schemas/PublicApiKeyDto"}},"pagination":{"$ref":"#/components/schemas/PaginationDto"}},"required":["data","pagination"],"x-pc-sdk-model":"ListPlatformApiKeys"},"CreatePakDto":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable PAK name (shown in the keys list).","example":"Production mail","minLength":1,"maxLength":120},"description":{"type":"string","description":"Optional description (e.g. which service uses the key).","maxLength":500,"example":"Sends receipts from the checkout service."},"policy_ids":{"description":"IDs of managed policies (workspace_policy rows) to bind to this PAK. Bind one or more — the PAK's effective policy is the union of all bound statements. Send exactly one of `policy_ids` and `preset`.","example":["11111111-1111-1111-1111-111111111111"],"type":"array","items":{"type":"string"}},"preset":{"type":"string","description":"A ready-made permission set to use instead of `policy_ids` (send exactly one of the two):\n\n- `mail-send` (Send email): Send email from your verified domains and check what happened to it. Cannot read message bodies or change domains.\n- `waitlist-write` (Waitlist sign-ups): Add and update sign-ups on your waitlists, and read the waitlists. Cannot export, delete or invite.\n- `trawl-jobs` (Extraction jobs): Start, cancel and read web-extraction jobs and their results.\n- `flags` (Manage flags): Create, edit, toggle and delete feature flags and segments in every environment, including protected ones, and manage projects and environments. Cannot reveal or rotate SDK keys, change webhooks or read confidential values.\n- `flags-dev` (Edit flags outside protected environments): Create and edit feature flags and segments, and change their values in environments that are not protected. Cannot touch protected environments, delete or see SDK keys.\n- `notify-send` (Send notifications): Send notifications, create and update recipients, mint recipient tokens for your apps and read the message log. Cannot change push credentials, notification types, settings or webhooks.\n- `notify-readonly` (Notify read-only): Read recipients, notification types, channels, settings, webhooks and the message log. Changes nothing and sends nothing.\n- `readonly` (Read-only): Read-only across the workspace: settings, members, email, waitlists, communities, web-extraction jobs, feature flags and notifications. Changes nothing.\n- `full` (Full access): Every action this workspace exposes, except creating keys, editing roles and policies, and other actions that hand out access. Use a custom policy for those.\n\nThe first key minted with a preset creates a managed policy for it in this workspace (named \"<label> preset\", `preset_key` set); later keys reuse that policy, so editing it changes every key bound to it. When the definition of a preset grows (a new product, for example), existing preset policies are updated to match, unless an owner has edited their statements. `readonly` and `full` are the same permission sets as the MCP connection presets of the same name. No preset can create keys, edit roles or policies, or hand out other access.","enum":["mail-send","waitlist-write","trawl-jobs","flags","flags-dev","notify-send","notify-readonly","readonly","full"],"example":"mail-send"},"expires_in_days":{"type":"number","description":"Lifetime of the key in days. Omit or send `null` for a key that never expires — the historical behaviour, what every PAK minted before this field existed holds, and still the default. Enforced at introspection: past `expires_at` the key resolves to 401 exactly like a revoked one.","enum":[30,90,365],"nullable":true,"example":90}},"required":["name"],"oneOf":[{"title":"Preset","description":"A ready-made permission set.","type":"object","properties":{"preset":{"type":"string"},"policy_ids":{"not":{}}},"required":["preset"]},{"title":"Policies","description":"Managed policies you wrote.","type":"object","properties":{"policy_ids":{"type":"array","items":{"type":"string"}},"preset":{"not":{}}},"required":["policy_ids"]}]},"MintPakResponseDto":{"type":"object","properties":{"token":{"type":"string","description":"The full plaintext PAK token. Returned ONCE — store it now; it cannot be retrieved later.","example":"pcft_live_abc123XYZ..."},"record":{"$ref":"#/components/schemas/PublicApiKeyDto"}},"required":["token","record"],"x-pc-sdk-model":"MintPak"},"PakPresetDto":{"type":"object","properties":{"key":{"description":"Preset to pass as `preset` when minting a key.","example":"mail-send","allOf":[{"$ref":"#/components/schemas/ApiKeyPresetKey"}]},"label":{"type":"string","description":"Short human label for the preset.","example":"Send email"},"description":{"type":"string","description":"What a key minted from this preset can do.","example":"Send email from your verified domains and check what happened to it. Cannot read message bodies or change domains."},"policy_id":{"type":"string","format":"uuid","nullable":true,"description":"The managed policy this preset created in this workspace when a key first used it; `null` until then. Keys minted with the preset bind this policy, edits included."},"allowed":{"example":["Mail: Send email from your verified domains"],"description":"What a key with this preset can do here, one plain sentence per action.","type":"array","items":{"type":"string"}},"actions":{"example":["mail.send"],"description":"The permission catalog actions behind `allowed`, in the same order.","type":"array","items":{"type":"string"}}},"required":["key","label","description","policy_id","allowed","actions"],"x-pc-sdk-model":"PakPreset"},"ListPakPresetsResponseDto":{"type":"object","properties":{"data":{"description":"Every preset a key can be minted from.","type":"array","items":{"$ref":"#/components/schemas/PakPresetDto"}},"pagination":{"description":"Always a single page: there are five presets.","allOf":[{"$ref":"#/components/schemas/PaginationDto"}]}},"required":["data","pagination"],"x-pc-sdk-model":"ListPakPresets"},"PreviewPakDto":{"type":"object","properties":{"policy_ids":{"description":"Managed policy ids the key would bind. Send exactly one of `policy_ids` and `preset`.","example":["11111111-1111-1111-1111-111111111111"],"type":"array","items":{"type":"string"}},"preset":{"type":"string","description":"The ready-made permission set the key would use. Send exactly one of `policy_ids` and `preset`.","enum":["mail-send","waitlist-write","trawl-jobs","flags","flags-dev","notify-send","notify-readonly","readonly","full"],"example":"readonly"}},"oneOf":[{"title":"Preset","description":"A ready-made permission set.","type":"object","properties":{"preset":{"type":"string"},"policy_ids":{"not":{}}},"required":["preset"]},{"title":"Policies","description":"Managed policies you wrote.","type":"object","properties":{"policy_ids":{"type":"array","items":{"type":"string"}},"preset":{"not":{}}},"required":["policy_ids"]}]},"PakGrantPreviewDto":{"type":"object","properties":{"allowed":{"example":["Mail: Read domains and templates","Mail: Send email from your verified domains"],"description":"What the key would be able to do, one plain sentence per action, as `<Product>: <action>` — the same sentences `GET /v1/api-keys/self` returns for a minted key. A sentence ends in `(only some resources)`, `(with exceptions)` or `(with conditions)` when the policy narrows it. Empty when the key could do nothing.","type":"array","items":{"type":"string"}},"actions":{"example":["mail.read","mail.send"],"description":"The permission catalog actions behind `allowed`, in the same order.","type":"array","items":{"type":"string"}},"grantable":{"type":"boolean","description":"Whether you may mint this key. `false` when it would hold an action you do not hold yourself; minting it would then fail with 403."},"refusal":{"type":"string","nullable":true,"example":null,"description":"Why a mint would be refused, when `grantable` is `false`; otherwise `null`."}},"required":["allowed","actions","grantable","refusal"],"x-pc-sdk-model":"PakGrantPreview"},"RotatePakDto":{"type":"object","properties":{"grace_hours":{"type":"number","description":"How long the OUTGOING key keeps working, in hours. `0` kills it immediately. Capped at 168 (7 days) — rotation answers \"this key may be compromised\", so an unbounded overlap would defeat the point. Rotation can only ever shorten a key: if the old one was already due to expire sooner, that earlier instant stands.","minimum":0,"maximum":168,"default":24,"example":24}}},"RotatePakResponseDto":{"type":"object","properties":{"token":{"type":"string","description":"The full plaintext PAK token. Returned ONCE — store it now; it cannot be retrieved later.","example":"pcft_live_abc123XYZ..."},"record":{"$ref":"#/components/schemas/PublicApiKeyDto"},"rotated_from":{"type":"string","format":"uuid","description":"Id of the key this one replaces."},"previous_key_expires_at":{"type":"string","format":"date-time","description":"When the replaced key stops introspecting. Until then BOTH keys work, so a fleet can roll over without downtime. Downstream services cache introspection for 60s, so treat this instant as \"+ up to a minute\" when planning a cutover."}},"required":["token","record","rotated_from","previous_key_expires_at"],"x-pc-sdk-model":"RotatePak"},"SetBindingsDto":{"type":"object","properties":{"policy_ids":{"description":"Replacement set of managed-policy IDs. Empty array is rejected — revoke the PAK to disable it.","example":["11111111-1111-1111-1111-111111111111"],"type":"array","items":{"type":"string"}}},"required":["policy_ids"]},"UpdatePakDto":{"type":"object","properties":{"name":{"type":"string","description":"New name of the key.","minLength":1,"maxLength":120,"example":"Production mail"},"description":{"type":"string","description":"New description of the key, or `null` to clear it.","nullable":true,"maxLength":500,"example":"Sends receipts from the checkout service."}}},"ApiKeySelfWorkspaceDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id of the workspace the key belongs to."},"slug":{"type":"string","example":"acme","description":"Slug of the workspace (the platform routes take it positionally)."},"name":{"type":"string","example":"Acme","description":"Display name of the workspace."}},"required":["id","slug","name"],"x-pc-sdk-model":"ApiKeySelfWorkspace"},"ApiKeySelfResponseDto":{"type":"object","properties":{"key_id":{"type":"string","format":"uuid","description":"Id of the key that made this request."},"name":{"type":"string","example":"Production mailer","description":"Name given to the key when it was minted."},"workspace_id":{"type":"string","format":"uuid","description":"Id of the workspace the key belongs to (also `workspace.id`). The SDKs read it once per process to bind `workspace_id` on product calls."},"workspace":{"description":"The workspace the key belongs to.","allOf":[{"$ref":"#/components/schemas/ApiKeySelfWorkspaceDto"}]},"expires_at":{"type":"string","nullable":true,"format":"date-time","description":"When the key stops working. `null` means it never expires."},"allowed":{"example":["Mail: Read domains and templates","Mail: Send email from your verified domains"],"description":"What the key may do, one plain sentence per action, as `<Product>: <action>`. A sentence ends in `(only some resources)` when the key holds the action on specific resources only, `(with exceptions)` when some resources are denied, and `(with conditions)` when it applies only under a condition. Empty when the key can do nothing.","type":"array","items":{"type":"string"}},"actions":{"example":["mail.read","mail.send"],"description":"The permission catalog actions behind `allowed`, in the same order.","type":"array","items":{"type":"string"}}},"required":["key_id","name","workspace_id","workspace","expires_at","allowed","actions"],"x-pc-sdk-model":"ApiKeySelf"},"AuditActorType":{"type":"string","enum":["platform_user","system","pat"]},"WorkspaceAuditLogEntryDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the entry.","format":"uuid"},"workspace_id":{"type":"string","description":"Id of the workspace.","format":"uuid"},"actor_id":{"type":"string","nullable":true,"description":"Account UUID of the actor, or null for system actions."},"actor_type":{"description":"Actor classification.","example":"platform_user","allOf":[{"$ref":"#/components/schemas/AuditActorType"}]},"action":{"type":"string","description":"Action identifier (e.g. `workspace.member.removed`). Product actions use the product name (`mail.*`, `waitlist.*`, `social.*`, `auth.*`).","example":"workspace.member.removed"},"resource":{"type":"string","description":"Resource type the action targeted.","example":"workspace_membership"},"resource_id":{"type":"string","description":"Id of the resource the action touched, when it has one.","nullable":true,"format":"uuid"},"ip":{"type":"string","nullable":true,"description":"Originating request IP, when available."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata attached to the audit row (jsonb)."},"created_at":{"type":"string","description":"When the action happened.","format":"date-time"}},"required":["id","workspace_id","actor_id","actor_type","action","resource","resource_id","ip","metadata","created_at"],"x-pc-sdk-model":"WorkspaceAuditLogEntry"},"ListWorkspaceAuditLogsResponseDto":{"type":"object","properties":{"data":{"description":"One page of audit log entries, newest first.","type":"array","items":{"$ref":"#/components/schemas/WorkspaceAuditLogEntryDto"}},"pagination":{"$ref":"#/components/schemas/PaginationDto"}},"required":["data","pagination"],"x-pc-sdk-model":"ListWorkspaceAuditLogs"},"AuditFeedSource":{"type":"string","enum":["workspace_audit","heimdall_audit","agora_moderation"]},"FeedItemDto":{"type":"object","properties":{"source":{"description":"Which audit table this row came from.","example":"workspace_audit","allOf":[{"$ref":"#/components/schemas/AuditFeedSource"}]},"timestamp":{"type":"string","description":"When the action happened.","format":"date-time"},"actor_id":{"type":"string","description":"Account id of the actor, or `null` for system actions.","nullable":true,"format":"uuid"},"actor_type":{"type":"string","description":"Actor classification — one of 'platform_user' | 'end_user' | 'm2m' | 'system' | 'pat' | 'api_key'.","example":"platform_user"},"action":{"type":"string","example":"mail.domain.verified","description":"Action identifier, `<product or scope>.<resource>.<verb>`. Product actions use the product name (`mail.*`, `waitlist.*`, `social.*`, `auth.*`)."},"resource":{"type":"string","description":"Kind of resource the action touched.","example":"workspace_membership"},"resource_id":{"type":"string","description":"Id of the resource, when it has one.","nullable":true,"format":"uuid"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata (jsonb)."},"source_ref":{"type":"string","description":"Stable per-source identifier. Used by the cursor to resume from the same point on the next page.","example":"4e5f5c9e-b4ee-4401-9275-283feb66c178"}},"required":["source","timestamp","actor_id","actor_type","action","resource","resource_id","metadata","source_ref"],"x-pc-sdk-model":"FeedItem"},"SourceDiagnosticDto":{"type":"object","properties":{"source":{"description":"The audit source this diagnostic describes.","allOf":[{"$ref":"#/components/schemas/AuditFeedSource"}]},"included":{"type":"boolean","description":"Whether the source contributed rows to this page."},"count":{"type":"number","description":"How many rows the source contributed."},"error":{"type":"string","description":"Why the source was skipped, when it failed (the feed still answers with the others)."}},"required":["source","included","count"],"x-pc-sdk-model":"SourceDiagnostic"},"AuditFeedResponseDto":{"type":"object","properties":{"data":{"description":"One page of feed items, newest first.","type":"array","items":{"$ref":"#/components/schemas/FeedItemDto"}},"pagination":{"$ref":"#/components/schemas/PaginationDto"},"sources":{"description":"Per-source diagnostics so the UI / customer can see which sources contributed to this page and which are stubbed pending the cross-service fanout.","type":"array","items":{"$ref":"#/components/schemas/SourceDiagnosticDto"}}},"required":["data","pagination","sources"],"x-pc-sdk-model":"AuditFeed"},"StatsWindow":{"type":"string","enum":["1d","7d","30d"]},"WorkspaceStatsTotalsDto":{"type":"object","properties":{"members":{"type":"number","description":"Members of the workspace.","example":4},"active_api_keys":{"type":"number","description":"Platform API keys that are neither revoked nor expired.","example":2}},"required":["members","active_api_keys"],"x-pc-sdk-model":"WorkspaceStatsTotals"},"WorkspaceStatsInWindowDto":{"type":"object","properties":{"audit_events":{"type":"number","description":"Admin changes in the window: workspace audit events that record a mutation (member, role, invite, service, API-key, policy, settings and consent changes, and the same from other products). Not counted: reads (any action ending `.read`, e.g. `workspace.member.read`, `workspace.audit.read`), sign-ins (`auth.signin.succeeded`) and MCP tool-call rows (`workspace.mcp_tool.*`; a mutating tool is counted through the change it makes). Opening the console does not move this number.","example":57},"last_api_key_use_at":{"type":"string","format":"date-time","nullable":true,"description":"Most recent use of any of the workspace's platform API keys within the window. Null when no key was used in the window.","example":"2026-10-07T06:12:40.000Z"}},"required":["audit_events","last_api_key_use_at"],"x-pc-sdk-model":"WorkspaceStatsInWindow"},"StatsMetric":{"type":"string","enum":["audit_events"]},"StatsGranularity":{"type":"string","enum":["day"]},"StatsSeriesPointDto":{"type":"object","properties":{"date":{"type":"string","description":"UTC calendar day.","format":"date","example":"2026-10-07"},"value":{"type":"number","description":"Value for that day.","example":7}},"required":["date","value"],"x-pc-sdk-model":"StatsSeriesPoint"},"WorkspaceStatsSeriesDto":{"type":"object","properties":{"metric":{"description":"Admin-change audit events per UTC day of `created_at` (same rows as `in_window.audit_events`: reads, sign-ins and MCP tool-call rows excluded).","example":"audit_events","allOf":[{"$ref":"#/components/schemas/StatsMetric"}]},"granularity":{"description":"Bucket width.","example":"day","allOf":[{"$ref":"#/components/schemas/StatsGranularity"}]},"points":{"description":"Dense and zero-filled: one point per UTC day in the window, oldest first, ending today.","type":"array","items":{"$ref":"#/components/schemas/StatsSeriesPointDto"}}},"required":["metric","granularity","points"],"x-pc-sdk-model":"WorkspaceStatsSeries"},"WorkspaceStatsDto":{"type":"object","properties":{"window":{"description":"Window the counts cover.","example":"30d","allOf":[{"$ref":"#/components/schemas/StatsWindow"}]},"generated_at":{"type":"string","format":"date-time","description":"When these numbers were computed. Responses are cached for up to 60 seconds.","example":"2026-10-07T09:00:00.000Z"},"last_activity_at":{"type":"string","format":"date-time","nullable":true,"description":"Most recent admin change (same definition as `in_window.audit_events`: reads, sign-ins and MCP tool-call rows excluded), any time. Null when none.","example":"2026-10-07T08:41:12.000Z"},"totals":{"description":"Current counts.","allOf":[{"$ref":"#/components/schemas/WorkspaceStatsTotalsDto"}]},"in_window":{"description":"Counts for the window.","allOf":[{"$ref":"#/components/schemas/WorkspaceStatsInWindowDto"}]},"series":{"description":"Daily admin changes.","allOf":[{"$ref":"#/components/schemas/WorkspaceStatsSeriesDto"}]}},"required":["window","generated_at","last_activity_at","totals","in_window","series"],"x-pc-sdk-model":"WorkspaceStats"},"MeProfileDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of your account.","format":"uuid"},"email":{"type":"string","description":"Your primary email, when you have one.","nullable":true},"username":{"type":"string","description":"Your username."},"display_name":{"type":"string","description":"Your display name, when set.","nullable":true},"status":{"type":"string","description":"Account status (e.g. `active`, `suspended`)."},"email_verified_at":{"type":"string","nullable":true,"format":"date-time","description":"Timestamp when this account verified its primary email, or null if unverified."},"avatar_url":{"type":"string","nullable":true,"description":"Short-lived (15 min) presigned GET URL for the avatar object in private object storage. NULL when no avatar has been set; the frontend then renders initials. The API mints a fresh URL on every response, so a stable bookmark of this value is not meaningful."}},"required":["id","email","username","display_name","status","email_verified_at","avatar_url"],"x-pc-sdk-model":"MeProfile"},"UpdateProfileDto":{"type":"object","properties":{"display_name":{"type":"string","description":"New display name. 1-128 chars. Optional — empty PATCH is a no-op.","example":"Ada Lovelace","minLength":1,"maxLength":128}}},"AvatarUrlResponseDto":{"type":"object","properties":{"avatar_url":{"type":"string","description":"URL of the uploaded avatar image."}},"required":["avatar_url"],"x-pc-sdk-model":"AvatarUrl"},"HiddenGuideDto":{"type":"object","properties":{"key":{"type":"string","description":"The guide: a surface name, optionally followed by `:` and the id of the resource the guide belongs to. The console uses `dashboard:<workspace id>`, `auth_app:<app id>`, `waitlist_quickstart:<waitlist id>`, `waitlist_steps:<workspace id>`, `community_quickstart:<community id>`, `trawl_quickstart:<workspace id>`, `flags_quickstart:<workspace id>`, `notify_quickstart:<workspace id>`, `mail_quickstart:<workspace id>`, and `all` for \"never show getting-started guides\".","pattern":"^[a-z][a-z0-9_]{0,39}(:[A-Za-z0-9_-]{1,64})?$","example":"auth_app:3f2c9a4e-8b1d-4c6e-9f2a-1b2c3d4e5f60"},"hidden_at":{"type":"string","format":"date-time","description":"When the guide was first hidden."}},"required":["key","hidden_at"],"x-pc-sdk-model":"HiddenGuide"},"HiddenGuidesDto":{"type":"object","properties":{"guides":{"description":"Every guide the caller has hidden, newest first. A bounded set (at most 200; hiding one more drops the oldest), so it is returned whole rather than paginated.","type":"array","items":{"$ref":"#/components/schemas/HiddenGuideDto"}}},"required":["guides"],"x-pc-sdk-model":"HiddenGuides"},"SessionDto":{"type":"object","properties":{"id":{"type":"string","description":"Session identifier","example":"sess_01HZY2G3A7M8Q9W4E6R2K1"},"account_id":{"type":"string","description":"Owning account identifier","example":"acc_01HZY2F2B6N7M8Q9W4E6R2"},"ip":{"type":"string","description":"Client IP address","nullable":true,"example":"203.0.113.42"},"user_agent":{"type":"string","description":"HTTP User-Agent string","nullable":true,"example":"Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"},"created_at":{"type":"string","description":"Creation timestamp (ISO 8601)","format":"date-time","example":"2025-09-20T12:34:56.000Z"},"expires_at":{"type":"string","description":"Expiration timestamp (ISO 8601)","format":"date-time","example":"2025-09-21T12:34:56.000Z"},"last_used_at":{"type":"string","description":"Last time this session was used (ISO 8601) or null","nullable":true,"format":"date-time","example":"2025-09-20T18:00:00.000Z"},"current":{"type":"boolean","description":"True for the session this request was made with (the caller's own browser or client). At most one session in the list is current.","example":true}},"required":["id","account_id","ip","user_agent","created_at","expires_at","last_used_at","current"],"x-pc-sdk-model":"Session"},"RevokeOtherSessionsResponseDto":{"type":"object","properties":{"revoked":{"type":"number","description":"How many of the caller's other active sessions this call signed out. 0 when there were none, so repeating the call is safe.","example":3,"minimum":0}},"required":["revoked"],"x-pc-sdk-model":"RevokeOtherSessions"},"RevokeSessionResponseDto":{"type":"object","properties":{"revoked":{"type":"boolean","description":"True when this call revoked the session; false when it was already revoked.","example":true}},"required":["revoked"],"x-pc-sdk-model":"RevokeSession"},"VerifyCodeDto":{"type":"object","properties":{"code":{"type":"string","description":"Verification code from the email link.","example":"a1b2c3d4…"}},"required":["code"]},"FeedbackResponseDto":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable message","example":"Email verified successfully"}},"required":["message"],"x-pc-sdk-model":"Feedback"},"JwkDto":{"type":"object","properties":{"kty":{"type":"string","description":"Key type (e.g. `RSA`).","example":"RSA"},"alg":{"type":"string","description":"Signing algorithm (e.g. `RS256`).","example":"RS256"},"kid":{"type":"string","description":"Key ID for matching the kid header on a JWT.","example":"k_2026_05_01"},"use":{"type":"string","description":"Key usage. Always `sig` for this endpoint.","example":"sig"}},"required":["kty","alg","kid","use"],"x-pc-sdk-model":"Jwk"},"JwksResponseDto":{"type":"object","properties":{"keys":{"description":"Array of public JWKs. Token verifiers iterate these by `kid` to find the matching signer.","type":"array","items":{"$ref":"#/components/schemas/JwkDto"}}},"required":["keys"],"x-pc-sdk-model":"Jwks"},"AuthorizationServerMetadataDto":{"type":"object","properties":{"issuer":{"type":"string","description":"Issuer identifier. Matches the `iss` claim on every access token this server mints.","example":"https://api.platform-auth.productcraft.co"},"authorization_endpoint":{"type":"string","description":"RFC 6749 authorization endpoint."},"token_endpoint":{"type":"string","description":"RFC 6749 token endpoint."},"registration_endpoint":{"type":"string","description":"RFC 7591 dynamic client registration endpoint."},"revocation_endpoint":{"type":"string","description":"RFC 7009 token revocation endpoint."},"introspection_endpoint":{"type":"string","description":"RFC 7662 token introspection endpoint."},"jwks_uri":{"type":"string","description":"JWKS the access-token signature verifies against."},"response_types_supported":{"description":"Only `code` — the implicit and password grants do not exist here.","example":["code"],"type":"array","items":{"type":"string"}},"grant_types_supported":{"description":"OAuth grant types the token endpoint accepts (RFC 8414).","example":["authorization_code","refresh_token"],"type":"array","items":{"type":"string"}},"code_challenge_methods_supported":{"description":"S256 only. `plain` is rejected, and an authorization request without a challenge is rejected.","example":["S256"],"type":"array","items":{"type":"string"}},"token_endpoint_auth_methods_supported":{"description":"Client authentication methods the token endpoint accepts (RFC 8414).","example":["none","client_secret_basic","client_secret_post"],"type":"array","items":{"type":"string"}},"scopes_supported":{"description":"Preset names accepted in the `scope` parameter. A preset is a policy *template*, never authority in itself — see `authority_model`. Ordinary OAuth scopes do not exist on this server.","example":["readonly","mail","support","full"],"type":"array","items":{"type":"string"}},"scope_descriptions":{"type":"object","additionalProperties":{"type":"string"},"description":"Plain-language description per preset. Non-standard, published so a client can render the same wording the consent screen uses."},"scope_labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Non-standard. Display name per preset (`readonly` is shown as \"Read-only\"), the same names the consent screen uses.","example":{"readonly":"Read-only","mail":"Email","support":"Support assistant","full":"Full access"}},"authority_model":{"type":"string","description":"Non-standard. Declares that authority on this server is an IAM policy document stored on the grant, intersected per request with the authorizing human’s current workspace policy — so a demotion or an offboarding takes effect on the next call rather than at token expiry. The `scope` parameter only names a preset the human then narrows.","example":"policy"},"resource_indicators_supported":{"description":"RFC 8707 resource indicators this server will mint an audience for.","type":"array","items":{"type":"string"}},"service_documentation":{"type":"string","description":"Human-readable documentation for this authorization server."}},"required":["issuer","authorization_endpoint","token_endpoint","registration_endpoint","revocation_endpoint","introspection_endpoint","jwks_uri","response_types_supported","grant_types_supported","code_challenge_methods_supported","token_endpoint_auth_methods_supported","scopes_supported","scope_descriptions","scope_labels","authority_model","resource_indicators_supported","service_documentation"],"x-pc-sdk-model":"AuthorizationServerMetadata"},"ClientRegistrationRequestDto":{"type":"object","properties":{"redirect_uris":{"description":"Exact redirect URIs. Matched byte-for-byte at `/authorize`; the only relaxation is the RFC 8252 §7.3 loopback port. `https` anywhere, `http` on `127.0.0.1` / `[::1]` only, or a reverse-DNS private-use scheme. No wildcards, no fragments.","example":["http://127.0.0.1:33418/callback"],"type":"array","items":{"type":"string"}},"client_name":{"type":"string","description":"Display name shown on the consent screen next to an \"unverified\" badge. Control characters are stripped; the client cannot supply any other consent-screen copy.","maxLength":120,"example":"Claude Desktop"},"grant_types":{"description":"Must include `authorization_code`. `refresh_token` is the only other supported value.","example":["authorization_code","refresh_token"],"type":"array","items":{"type":"string"}},"response_types":{"description":"Only `code` is supported.","example":["code"],"type":"array","items":{"type":"string"}},"token_endpoint_auth_method":{"type":"string","description":"`none` for a public client (PKCE only), or `client_secret_basic` / `client_secret_post` for a confidential client. Defaults to `none`.","example":"none"},"scope":{"type":"string","description":"Space-delimited ceiling of scopes this client may ever request. Defaults to the full published scope list; the human still approves each one.","example":"workspace:read mail:read mail:send"},"client_uri":{"type":"string","nullable":true,"description":"Absolute https homepage for the client."},"logo_uri":{"type":"string","nullable":true,"description":"Absolute https logo URL. Stored but deliberately never rendered on the consent screen — a client-supplied image is client-supplied display text by another name."}},"required":["redirect_uris","client_name"]},"ClientRegistrationResponseDto":{"type":"object","properties":{"client_id":{"type":"string","example":"pcft_cli_2f5c..."},"client_id_issued_at":{"type":"number","description":"Unix seconds at which the client_id was issued."},"client_secret_expires_at":{"type":"number","description":"0 — the client secret does not expire on its own.","example":0},"registration_client_uri":{"type":"string","description":"Endpoint the registration access token is used against."},"redirect_uris":{"type":"array","items":{"type":"string"}},"client_name":{"type":"string"},"grant_types":{"type":"array","items":{"type":"string"}},"response_types":{"type":"array","items":{"type":"string"}},"token_endpoint_auth_method":{"type":"string"},"scope":{"type":"string"},"is_verified":{"type":"boolean","description":"Always false for a dynamically registered client. The consent screen shows this to the human.","example":false},"client_secret":{"type":"string","nullable":true,"description":"Returned exactly once, and only for confidential clients. Stored hashed; it cannot be retrieved again."},"registration_access_token":{"type":"string","description":"Bearer token that reads and updates THIS registration and nothing else. Returned once."}},"required":["client_id","client_id_issued_at","client_secret_expires_at","registration_client_uri","redirect_uris","client_name","grant_types","response_types","token_endpoint_auth_method","scope","is_verified","client_secret","registration_access_token"]},"OAuthErrorResponseDto":{"type":"object","properties":{"error":{"type":"string","description":"OAuth error code (RFC 6749 §5.2, RFC 7591 §3.2.2, RFC 8707).","enum":["invalid_request","invalid_client","invalid_grant","unauthorized_client","unsupported_grant_type","unsupported_response_type","invalid_scope","access_denied","server_error","temporarily_unavailable","invalid_target","invalid_redirect_uri","invalid_client_metadata","invalid_token"],"example":"invalid_grant"},"error_description":{"type":"string","description":"Human-readable explanation of the error.","example":"Authorization code is invalid, expired, or already used"}},"required":["error","error_description"]},"ClientMetadataDto":{"type":"object","properties":{"client_id":{"type":"string","example":"pcft_cli_2f5c..."},"client_id_issued_at":{"type":"number","description":"Unix seconds at which the client_id was issued."},"client_secret_expires_at":{"type":"number","description":"0 — the client secret does not expire on its own.","example":0},"registration_client_uri":{"type":"string","description":"Endpoint the registration access token is used against."},"redirect_uris":{"type":"array","items":{"type":"string"}},"client_name":{"type":"string"},"grant_types":{"type":"array","items":{"type":"string"}},"response_types":{"type":"array","items":{"type":"string"}},"token_endpoint_auth_method":{"type":"string"},"scope":{"type":"string"},"is_verified":{"type":"boolean","description":"Always false for a dynamically registered client. The consent screen shows this to the human.","example":false}},"required":["client_id","client_id_issued_at","client_secret_expires_at","registration_client_uri","redirect_uris","client_name","grant_types","response_types","token_endpoint_auth_method","scope","is_verified"]},"ConsentPresetDto":{"type":"object","properties":{"preset":{"type":"string","description":"Preset name the client asked for. A preset is a policy *template*, never authority in itself.","example":"mail","enum":["readonly","mail","support","full"]},"label":{"type":"string","description":"Server-authored display name for the preset. The client cannot influence it.","example":"Email"},"description":{"type":"string","description":"Server-authored plain-language wording. The client cannot influence it.","example":"Read and send email from your verified domains."}},"required":["preset","label","description"]},"ConsentWorkspaceDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"display_name":{"type":"string"},"role":{"type":"string","description":"Caller's role in this workspace.","example":"owner"},"enabled_products":{"type":"array","description":"Products this workspace has switched on. The consent screen pre-selects these when the connect link named no products.","example":["mail","waitlist"],"items":{"type":"string","enum":["auth","mail","waitlist","social","trawl","flags","notify"]}}},"required":["id","slug","display_name","role","enabled_products"]},"ConsentProductDto":{"type":"object","properties":{"product":{"type":"string","enum":["auth","mail","waitlist","social","trawl","flags","notify"],"description":"Product key, as sent back in the decision.","example":"mail"},"label":{"type":"string","description":"Customer-facing name.","example":"Mail"}},"required":["product","label"]},"ConsentRequestDto":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"client_id":{"type":"string"},"client_name":{"type":"string","description":"Display name the client registered with."},"client_uri":{"type":"string","nullable":true},"is_verified":{"type":"boolean","description":"False for every dynamically registered client. The screen must show this prominently."},"presets":{"description":"Presets the client requested. The consent screen renders these in one line each.","type":"array","items":{"$ref":"#/components/schemas/ConsentPresetDto"}},"requested_policy":{"description":"The policy the presets resolve to — the starting point the human narrows. Authority is whatever they approve.","type":"array","items":{"$ref":"#/components/schemas/PolicyStatementDto"}},"escalation_actions":{"description":"Escalation actions (credential minting, role/policy editing, m2m issuance) the requested policy would grant. Always empty for a preset; the consent screen must surface any entry here in its own section, not among ordinary permissions.","example":[],"type":"array","items":{"type":"string"}},"resource":{"type":"string","description":"RFC 8707 resource the token will be audience-bound to."},"workspaces":{"description":"Workspaces the human may pick from. Access is scoped to exactly one.","type":"array","items":{"$ref":"#/components/schemas/ConsentWorkspaceDto"}},"products":{"description":"Every product a connection can be limited to, in display order. The assistant is offered only the tools of the products the human ticks, plus the workspace basics.","type":"array","items":{"$ref":"#/components/schemas/ConsentProductDto"}},"requested_products":{"type":"array","nullable":true,"description":"Products the connect link asked to pre-select (`/mcp?products=mail,waitlist`, or `products=` on `/authorize`). Null when it named none; the screen then pre-selects the workspace’s enabled products.","example":["mail"],"items":{"type":"string","enum":["auth","mail","waitlist","social","trawl","flags","notify"]}},"expires_at":{"type":"string","format":"date-time"}},"required":["request_id","client_id","client_name","client_uri","is_verified","presets","requested_policy","escalation_actions","resource","workspaces","products","requested_products","expires_at"]},"ConsentDecisionDto":{"type":"object","properties":{"approved":{"type":"boolean","description":"True to approve, false to deny."},"workspace_id":{"type":"string","format":"uuid","description":"Workspace the grant is scoped to. Required when approving."},"policy":{"description":"The policy the human approved. Defaults to the policy the requested presets resolve to. May narrow it, and may add an escalation action a preset withheld — but never beyond the human's own authority: a grant that exceeds the granter is refused with 403 and the response names the refused statements.","type":"array","items":{"$ref":"#/components/schemas/PolicyStatementDto"}},"products":{"type":"array","nullable":true,"description":"Products the connection is limited to: the assistant is offered only their tools, plus the workspace basics, and a call to any other product’s tool is refused. Omitted or null means every product. An empty list leaves only the workspace basics.","example":["mail","waitlist"],"items":{"type":"string","enum":["auth","mail","waitlist","social","trawl","flags","notify"]}}},"required":["approved"]},"ConsentDecisionResponseDto":{"type":"object","properties":{"redirect_to":{"type":"string","description":"Absolute URL the browser must be sent to. Always the redirect URI captured when the request was created."}},"required":["redirect_to"]},"McpProduct":{"type":"string","enum":["auth","mail","waitlist","social","trawl","flags","notify"]},"ConnectedClientDto":{"type":"object","properties":{"grant_id":{"type":"string","description":"Id of the grant (pass it to disconnect).","format":"uuid"},"client_id":{"type":"string","description":"OAuth `client_id` of the connected app."},"client_name":{"type":"string","description":"Name the app registered with."},"is_verified":{"type":"boolean","description":"Whether ProductCraft verified the app (dynamically registered apps never are)."},"account_id":{"type":"string","format":"uuid","description":"The human who consented to this grant."},"workspace_id":{"type":"string","description":"Id of the workspace the grant is scoped to.","format":"uuid"},"preset":{"type":"string","nullable":true,"description":"Preset the grant started from, when it started from one.","example":"mail"},"policy":{"description":"Policy the human approved. Effective authority is this intersected with the human's current workspace policy, per request.","type":"array","items":{"$ref":"#/components/schemas/PolicyStatementDto"}},"resource":{"type":"string","description":"Resource indicator the grant's tokens are bound to."},"products":{"type":"array","nullable":true,"description":"Products this connection is limited to. Null means every product (every connection made before products could be chosen).","example":["mail"],"items":{"$ref":"#/components/schemas/McpProduct"}},"first_tool_call_at":{"type":"string","nullable":true,"format":"date-time","description":"When the assistant made its first successful tool call through this connection. Null until then, which is how a client that authorized but never worked shows up."},"created_at":{"type":"string","description":"When access was granted.","format":"date-time"},"revoked_at":{"type":"string","description":"When the grant was revoked, or `null` while it is live.","nullable":true,"format":"date-time"}},"required":["grant_id","client_id","client_name","is_verified","account_id","workspace_id","preset","policy","resource","products","first_tool_call_at","created_at","revoked_at"],"x-pc-sdk-model":"ConnectedClient"},"ConnectedClientListDto":{"type":"object","properties":{"data":{"description":"One page of connected apps.","type":"array","items":{"$ref":"#/components/schemas/ConnectedClientDto"}},"pagination":{"$ref":"#/components/schemas/PaginationDto"}},"required":["data","pagination"],"x-pc-sdk-model":"ConnectedClientList"},"TokenRequestDto":{"type":"object","properties":{"grant_type":{"type":"string","description":"`authorization_code` or `refresh_token`.","example":"authorization_code"},"code":{"type":"string","description":"The single-use authorization code. `authorization_code` grant only."},"code_verifier":{"type":"string","description":"PKCE verifier. Required on the `authorization_code` grant — there is no non-PKCE path."},"redirect_uri":{"type":"string","description":"Must be byte-identical to the `redirect_uri` used at `/authorize`. `authorization_code` grant only."},"refresh_token":{"type":"string","description":"The rotating refresh token. `refresh_token` grant only."},"client_id":{"type":"string","description":"Client identifier. Required for public clients; confidential clients may instead use HTTP Basic."},"client_secret":{"type":"string","description":"Client secret for `client_secret_post` authentication."},"scope":{"type":"string","description":"Narrowed preset name(s) on the `refresh_token` grant. A preset the original grant did not carry is rejected; narrowing keeps every deny and only removes actions, so it can never widen."},"resource":{"type":"string","description":"RFC 8707 resource indicator. Must match the one the grant was created for."}},"required":["grant_type"]},"OAuthTokenResponseDto":{"type":"object","properties":{"access_token":{"type":"string","description":"Signed JWT, audience-bound to the resource indicator and carrying the workspace, the preset name and the client id. It carries no policy — authority is resolved per request from the grant row and the human’s live policy."},"token_type":{"type":"string","example":"Bearer"},"expires_in":{"type":"number","description":"Seconds until the access token expires (≤ 900).","example":900},"refresh_token":{"type":"string","description":"Rotating refresh token. The one presented is consumed; replaying it revokes the whole grant family."},"scope":{"type":"string","description":"Preset name(s) the grant started from. Present for RFC 6749 §5.1 compliance; it is not the authority — `policy` is.","example":"mail"},"policy":{"description":"The policy this token carries. Effective authority is this intersected with the authorizing human's current workspace policy, re-evaluated on every call.","type":"array","items":{"$ref":"#/components/schemas/PolicyStatementDto"}},"workspace_id":{"type":"string","format":"uuid","description":"Workspace the grant is scoped to."}},"required":["access_token","token_type","expires_in","refresh_token","scope","policy","workspace_id"]},"RevocationRequestDto":{"type":"object","properties":{"token":{"type":"string","description":"The access or refresh token to revoke."},"token_type_hint":{"type":"string","description":"`access_token` or `refresh_token`. Advisory only."},"client_id":{"type":"string"},"client_secret":{"type":"string"}},"required":["token"]},"IntrospectionRequestDto":{"type":"object","properties":{"token":{"type":"string","description":"The access token to introspect."},"client_id":{"type":"string"},"client_secret":{"type":"string"}},"required":["token"]},"IntrospectionResponseDto":{"type":"object","properties":{"active":{"type":"boolean","description":"False for an unknown, expired, revoked, or foreign token — the four are deliberately indistinguishable."},"scope":{"type":"string","description":"Preset name(s) the grant started from. Not authority."},"client_id":{"type":"string"},"sub":{"type":"string","format":"uuid","description":"The human who consented."},"workspace_id":{"type":"string","format":"uuid"},"aud":{"type":"string","description":"Resource indicator the token is bound to."},"exp":{"type":"number","description":"Expiry, unix seconds."},"policy":{"description":"The policy stored on the token — the ceiling the human approved at consent.","type":"array","items":{"$ref":"#/components/schemas/PolicyStatementDto"}},"effective_policy":{"description":"Effective authority: the token's policy intersected with the human's CURRENT workspace policy, recomputed on every call with no cache. An action the human's role loses disappears here without anyone revoking the token; a human who left the workspace makes the token report `active: false`. This is a report — the authorization decision itself re-evaluates both policies per (action, resource) cell.","type":"array","items":{"$ref":"#/components/schemas/PolicyStatementDto"}}},"required":["active"]},"DelegatedAuthorizationRequestDto":{"type":"object","properties":{"action":{"type":"string","description":"The action to decide, in `<service>.<resource>.<verb>` form — the same catalogue the workspace-role and PAK lanes evaluate against.","example":"mail.message.send","maxLength":200},"resource":{"type":"string","description":"Resource URN the action targets. Omitted means `*`, which the human’s URN-narrowed denies still constrain.","example":"pcft:envoi:domain/8f14e45f-ceea-467a-9c1a-2b8a4f2a11c3","maxLength":500}},"required":["action"]},"DelegatedAuthorizationResponseDto":{"type":"object","properties":{"allowed":{"type":"boolean","description":"Whether the effective policy — the grant’s policy AND the authorizing human’s current workspace policy — allows this action right now."},"reason":{"type":"string","description":"Machine-readable outcome: `allowed`, `denied_by_effective_policy`, `service_not_enabled` (the workspace switched the product off), `product_not_in_connection` (the human left this product out when connecting), `token_inactive`, `token_expired`, `grant_revoked`, `granter_not_a_member`, or `granter_account_inactive` (the authorizing human’s account is suspended or deactivated).","example":"allowed"}},"required":["allowed","reason"]},"DelegatedAuthorizationBatchRequestDto":{"type":"object","properties":{"actions":{"description":"Actions to decide, in `<service>.<resource>.<verb>` form. Duplicates are evaluated once and echoed per entry.","example":["mail.send","mail.list"],"maxItems":500,"type":"array","items":{"type":"string"}},"resource":{"type":"string","description":"Resource URN every action is decided against. Omitted means `*`, which the human’s URN-narrowed denies still constrain.","example":"pcft:envoi:domain/8f14e45f-ceea-467a-9c1a-2b8a4f2a11c3","maxLength":500}},"required":["actions"]},"DelegatedActionDecisionDto":{"type":"object","properties":{"action":{"type":"string","description":"The action that was decided.","example":"mail.send"},"allowed":{"type":"boolean","description":"Whether the effective policy allows this action at the requested resource right now."}},"required":["action","allowed"]},"DelegatedAuthorizationBatchResponseDto":{"type":"object","properties":{"decisions":{"description":"One decision per requested action, in the order they were requested.","type":"array","items":{"$ref":"#/components/schemas/DelegatedActionDecisionDto"}},"reason":{"type":"string","description":"Machine-readable outcome for the token as a whole: `evaluated`, `token_inactive`, `token_expired`, `grant_revoked`, `granter_not_a_member`, or `granter_account_inactive`. Anything but `evaluated` means every decision is `false`.","example":"evaluated"}},"required":["decisions","reason"]},"DownstreamAssertionRequestDto":{"type":"object","properties":{"audience":{"type":"string","description":"Hostname of the service the assertion is for, e.g. `api.mail.productcraft.co`. Must be one we issue for; anything else is 400. This is an allowlist and not a free-text audience, because the audience string is what separates this family from the session lane.","example":"api.mail.productcraft.co"}},"required":["audience"]},"DownstreamAssertionResponseDto":{"type":"object","properties":{"assertion":{"type":"string","description":"The signed assertion. Verifies offline against the platform JWKS. Carries identity only — no policy."},"expires_in":{"type":"number","description":"Seconds until it expires. Deliberately short.","example":60},"audience":{"type":"string","description":"The audience it was minted for, echoed back.","example":"api.mail.productcraft.co"}},"required":["assertion","expires_in","audience"]},"AssertionAuthorizationRequestDto":{"type":"object","properties":{"action":{"type":"string","description":"Action to decide, `<service>.<resource>.<verb>`."},"resource":{"type":"string","description":"URN the action targets. Omitted means `*`, the strict reading."}},"required":["action"]},"PlatformErrorCode":{"description":"Error codes this API returns (open set: a client must accept codes it does not know; new codes are not a breaking change). Each is documented at https://productcraft.co/docs/errors#<code>.","anyOf":[{"type":"string","enum":["BAD_REQUEST","VALIDATION_ERROR","UNAUTHORIZED","PAYMENT_REQUIRED","FORBIDDEN","NOT_FOUND","METHOD_NOT_ALLOWED","NOT_ACCEPTABLE","REQUEST_TIMEOUT","CONFLICT","GONE","PRECONDITION_FAILED","PAYLOAD_TOO_LARGE","UNSUPPORTED_MEDIA_TYPE","UNPROCESSABLE_ENTITY","PRECONDITION_REQUIRED","RATE_LIMITED","INTERNAL_SERVER_ERROR","NOT_IMPLEMENTED","BAD_GATEWAY","SERVICE_UNAVAILABLE","GATEWAY_TIMEOUT","SERVICE_NOT_ENABLED","INVALID_CREDENTIALS","SESSION_REVOKED","MCP_NOT_PERMITTED","MCP_WORKSPACE_MISMATCH","PAK_NOT_PERMITTED","ACTIONS_NOT_GRANTABLE","IDEMPOTENCY_KEY_REUSE","IDEMPOTENCY_KEY_REQUIRED","IDEMPOTENCY_IN_PROGRESS","ACCOUNT_DEACTIVATED","ACCOUNT_SUSPENDED","ALREADY_A_MEMBER","CROSS_ORIGIN_REJECTED","EMAIL_NOT_VERIFIED","HUMAN_SESSION_REQUIRED","INVITE_EMAIL_MISMATCH","INVITE_EXHAUSTED","INVITE_EXPIRED","INVITE_INVALID","INVITE_NOT_FOUND","INVITE_REVOKED","INVITE_ROLE_DELETED","LAST_MEMBER","MEMBER_RANK_EXCEEDED","MFA_CHALLENGE_INVALID","MFA_CODE_INVALID","MFA_ENROLLMENT_REQUIRED","MFA_FACTOR_EXISTS","MFA_FACTOR_NOT_FOUND","MFA_REQUIRED_BY_WORKSPACE","NOT_A_MEMBER","OAUTH_GRANT_ADMIN_REVOKED","OWNER_ROLE_REQUIRED","PAK_ALREADY_MINTED","PAK_EXPIRED","PAK_NAME_REQUIRED","PAK_NAME_TOO_LONG","PAK_NOT_FOUND","PAK_REVOKED","PASSWORD_RESET_INVALID","POLICY_INVALID","POLICY_NAME_TAKEN","POLICY_NOT_FOUND","ROLE_HAS_MEMBERS","ROLE_NAME_TAKEN","ROLE_NOT_FOUND","ROLE_SYSTEM_IMMUTABLE","SERVICE_NOT_ACTIVATED","SERVICE_UNKNOWN","SOLE_OWNER","STEP_UP_REQUIRED","TOO_MANY_ATTEMPTS","WORKSPACE_KEY_REQUIRED"]},{"type":"string","description":"A code added after this document was published."}],"x-pc-open-enum":true,"x-pc-error-docs":"https://productcraft.co/docs/errors#{code}","x-enum-descriptions":{"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.","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.","HUMAN_SESSION_REQUIRED":"This route needs a person's own session; workspace API keys and OAuth/MCP tokens cannot use it.","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.","INVITE_ROLE_DELETED":"The role this invite granted has been deleted; ask for a new invite.","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.","MFA_CHALLENGE_INVALID":"The two-step sign-in challenge is unknown, expired, used or out of tries; sign in again.","MFA_CODE_INVALID":"The two-step code, recovery code or passkey was not accepted.","MFA_ENROLLMENT_REQUIRED":"Set up two-step sign-in first: the workspace requires it.","MFA_FACTOR_EXISTS":"Email codes are already on for this account, or this passkey is already registered.","MFA_FACTOR_NOT_FOUND":"No two-step sign-in method with this id on your account.","MFA_REQUIRED_BY_WORKSPACE":"A workspace you belong to requires two-step sign-in, so the last method cannot be removed.","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.","STEP_UP_REQUIRED":"Confirm it is you (a fresh two-step check) before this action; `details.methods` lists how.","TOO_MANY_ATTEMPTS":"Too many attempts; wait before trying again.","WORKSPACE_KEY_REQUIRED":"This route needs a workspace API key."}}},"headers":{"RequestId":{"description":"The request's id: the inbound `X-Request-Id` when it is 1 to 128 characters of `A-Z a-z 0-9 . _ : -`, otherwise a fresh `req_...` id. Error bodies repeat it as `request_id`. Quote it when contacting support.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","example":"req_6f1c2a9d4b7e4f0a8c3d2e1f0a9b8c7d"}}}}}