picked 0.0.101-next.2 → 0.0.101

package/docs/reference/management-api/schema/auth.md

@@ -0,0 +1,1177 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Auth schema
+
+The operations and types that `auth.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Queries
+
+### `user`
+
+Fetch the currently authenticated user. Returns null if the request is unauthenticated. Exempt from the MFA policy, so a gated user can read `mfa` and `mfaFactors`.
+
+```graphql
+user: User @auth(mfa: EXEMPT)
+```
+
+### `viewerScopes`
+
+Root-level scopes for the authenticated user (e.g. `ORGANIZATION_CREATE`, `STAFF_READ`). Use `Organization.viewerScopes` for org-scoped scopes.
+
+```graphql
+viewerScopes: [Scope!]! @auth
+```
+
+### `oauthConsentDetails`
+
+Get OAuth consent authorisation details. Requires authentication (USER token only).
+
+```graphql
+oauthConsentDetails(input: OAuthConsentDetailsInput!): OAuthConsentDetailsPayload! @auth(only: USER)
+```
+
+## Mutations
+
+### `sessionStart`
+
+Begin signing in with an email address alone. Answers `PASSWORD` when the
+account has set a password, and otherwise emails a sign-in code and link and
+answers `EMAIL_CODE`. Never creates an account. Returns `RATE_LIMITED` when
+the caller makes too many requests, or when the project's email quota is spent.
+
+```graphql
+sessionStart(input: SessionStartInput!): SessionStartPayload!
+```
+
+### `sessionCreate`
+
+Create a new session by signing in with email and password.
+
+```graphql
+sessionCreate(input: SessionCreateInput!): SessionCreatePayload!
+```
+
+### `sessionRefresh`
+
+Refresh an existing session using a refresh token.
+
+```graphql
+sessionRefresh(input: SessionRefreshInput!): SessionRefreshPayload!
+```
+
+### `accountCreate`
+
+Register an email address and send it a confirmation email.
+
+```graphql
+accountCreate(input: AccountCreateInput!): AccountCreatePayload!
+```
+
+### `accountVerifyEmail`
+
+Verify a user's email address with a confirmation token.
+
+```graphql
+accountVerifyEmail(input: AccountVerifyEmailInput!): AccountVerifyEmailPayload!
+```
+
+### `accountResendVerification`
+
+Resend the email verification link.
+
+```graphql
+accountResendVerification(input: AccountResendVerificationInput!): AccountResendVerificationPayload!
+```
+
+### `oauthAuthorize`
+
+Initiate an OAuth authorisation flow.
+
+```graphql
+oauthAuthorize(input: OAuthAuthorizeInput!): OAuthAuthorizePayload!
+```
+
+### `oauthCallback`
+
+Handle the OAuth callback and create a session.
+
+```graphql
+oauthCallback(input: OAuthCallbackInput!): OAuthCallbackPayload!
+```
+
+### `oauthConsentApprove`
+
+Approve an OAuth consent request. Requires authentication.
+
+```graphql
+oauthConsentApprove(input: OAuthConsentApproveInput!): OAuthConsentActionPayload! @auth(only: USER)
+```
+
+### `oauthConsentDeny`
+
+Deny an OAuth consent request. Requires authentication.
+
+```graphql
+oauthConsentDeny(input: OAuthConsentDenyInput!): OAuthConsentActionPayload! @auth(only: USER)
+```
+
+### `magicLinkSend`
+
+Email an existing account a sign-in code and link. Never creates an account,
+and answers `success: true` for an address with no account.
+
+```graphql
+magicLinkSend(input: MagicLinkSendInput!): MagicLinkSendPayload!
+```
+
+### `magicLinkVerify`
+
+Verify the code from a sign-in or confirmation email and create a session.
+
+```graphql
+magicLinkVerify(input: MagicLinkVerifyInput!): MagicLinkVerifyPayload!
+```
+
+### `emailLinkVerify`
+
+Verify the link from a password-reset, invitation, sign-in or confirmation
+email and create a session. The link is single-use, so call this when the
+recipient confirms, never on opening the link: an email security scanner that
+opens links before delivery would otherwise use it up.
+
+```graphql
+emailLinkVerify(input: EmailLinkVerifyInput!): EmailLinkVerifyPayload!
+```
+
+### `passwordResetSend`
+
+Send a password reset email.
+
+```graphql
+passwordResetSend(input: PasswordResetSendInput!): PasswordResetSendPayload!
+```
+
+### `passwordUpdate`
+
+Update the current user's password. Requires authentication. An `AAL1` session
+may set a password only while the user holds no verified factor, and is
+otherwise refused with `MFA_REQUIRED`.
+
+```graphql
+passwordUpdate(input: PasswordUpdateInput!): PasswordUpdatePayload! @auth(mfa: EXEMPT)
+```
+
+### `mfaFactorEnroll`
+
+Enrol an authenticator app for the caller. Requires a user session; exempt from the MFA policy.
+
+```graphql
+mfaFactorEnroll(input: MfaFactorEnrollInput!): MfaFactorEnrollPayload! @auth(only: USER, mfa: EXEMPT)
+```
+
+### `mfaChallengeCreate`
+
+Open a challenge against one of the caller's factors. Requires a user session; exempt from the MFA policy.
+
+```graphql
+mfaChallengeCreate(input: MfaChallengeCreateInput!): MfaChallengeCreatePayload! @auth(only: USER, mfa: EXEMPT)
+```
+
+### `mfaChallengeVerify`
+
+Verify a code against a challenge and lift the caller's session to `AAL2`. Requires a user session; exempt from the MFA policy.
+
+```graphql
+mfaChallengeVerify(input: MfaChallengeVerifyInput!): MfaChallengeVerifyPayload! @auth(only: USER, mfa: EXEMPT)
+```
+
+### `mfaFactorUnenroll`
+
+Remove one of the caller's factors. Requires a user session; exempt from the MFA policy, though removing a verified factor needs `AAL2`.
+
+```graphql
+mfaFactorUnenroll(input: MfaFactorUnenrollInput!): MfaFactorUnenrollPayload! @auth(only: USER, mfa: EXEMPT)
+```
+
+## Types
+
+### `AuthErrorCode`
+
+```graphql
+"""
+Programmatic error codes returned by auth use cases. Surfaced via the
+standard GraphQL `errors` array's `extensions.code` when an `AuthError` is
+thrown. Use these to drive client-side UX (e.g. show "invalid password"
+vs "email not confirmed" messages) — do not parse the `message` string.
+"""
+enum AuthErrorCode {
+  """The provided credentials are invalid (wrong password, unknown email)."""
+  INVALID_CREDENTIALS
+  """
+  The user's email address has not yet been confirmed via the verification link.
+  """
+  EMAIL_NOT_CONFIRMED
+  """No user was found matching the provided criteria."""
+  USER_NOT_FOUND
+  """A user with the provided email already exists."""
+  USER_ALREADY_EXISTS
+  """
+  The provided password does not meet the strength requirements enforced by Supabase Auth.
+  """
+  WEAK_PASSWORD
+  """
+  The provided token is invalid (malformed, signature mismatch, or not issued by this server).
+  """
+  INVALID_TOKEN
+  """The provided token has expired."""
+  TOKEN_EXPIRED
+  """
+  The MFA challenge verification failed (wrong code or rejected challenge).
+  """
+  MFA_CHALLENGE_FAILED
+  """
+  The specified MFA factor was not found, or does not belong to the caller.
+  """
+  MFA_FACTOR_NOT_FOUND
+  """
+  The caller must hold an `AAL2` session: they are staff, or a member of an
+  organisation that requires two-factor authentication, or the operation itself
+  needs a verified second factor (removing a verified factor). Verify a factor
+  with `mfaChallengeVerify` and retry with the returned session.
+  """
+  MFA_REQUIRED
+  """
+  An error occurred while exchanging credentials with the upstream OAuth provider.
+  """
+  OAUTH_PROVIDER_ERROR
+  """
+  Too many requests; the operation has been rate-limited by Supabase Auth.
+  """
+  RATE_LIMITED
+}
+```
+
+### `AuthenticatorAssuranceLevel`
+
+```graphql
+"""
+Authenticator Assurance Level — how many factors the active session has
+satisfied. Conforms to the NIST 800-63 AAL definitions.
+
+`AAL1` means the session is authenticated with a single factor (password
+or OAuth). `AAL2` means the session has additionally verified a TOTP
+factor. The level is decoded from the session's access token; a call that
+lifts a session from `AAL1` to `AAL2` goes through `mfaChallengeVerify`.
+"""
+enum AuthenticatorAssuranceLevel {
+  """Single-factor authentication (password or OAuth only)."""
+  AAL1
+  """
+  Multi-factor authentication (a verified TOTP code on top of the first factor).
+  """
+  AAL2
+}
+```
+
+### `IdentityProvider`
+
+```graphql
+"""
+Identity provider types — which upstream issued the credential the user
+authenticated with. A `User` may have multiple `Identity` records (e.g.
+linked Google + password).
+"""
+enum IdentityProvider {
+  """Email + password authentication."""
+  EMAIL
+  """Google OAuth authentication."""
+  GOOGLE
+}
+```
+
+### `OAuthProvider`
+
+```graphql
+"""
+OAuth providers supported for end-user authentication. Used by
+`oauthAuthorize` to select the provider URL to redirect the user to.
+"""
+enum OAuthProvider {
+  """Google OAuth provider."""
+  GOOGLE
+}
+```
+
+### `MfaFactorType`
+
+```graphql
+"""
+MFA factor types. Time-based one-time passwords from an authenticator app are the only kind.
+"""
+enum MfaFactorType {
+  """
+  An authenticator app generating time-based one-time passwords (RFC 6238).
+  """
+  TOTP
+}
+```
+
+### `MfaFactorStatus`
+
+```graphql
+"""
+MFA factor verification status. A factor created by `mfaFactorEnroll`
+starts as `UNVERIFIED`; once the user verifies a code from their
+authenticator via `mfaChallengeVerify`, it transitions to `VERIFIED`.
+"""
+enum MfaFactorStatus {
+  """
+  Factor has been enrolled but the user has not yet verified a delivered code.
+  """
+  UNVERIFIED
+  """Factor has been verified and is active."""
+  VERIFIED
+}
+```
+
+### `MfaState`
+
+```graphql
+"""
+Whether a user has completed multi-factor authentication enrolment. `ENROLLED`
+means at least one verified MFA factor exists for the user; `NOT_ENROLLED` means
+none does. Shown beside a user in every dashboard list of users.
+"""
+enum MfaState {
+  """The user holds at least one verified MFA factor."""
+  ENROLLED
+  """The user holds no verified MFA factor."""
+  NOT_ENROLLED
+}
+```
+
+### `Identity`
+
+```graphql
+"""
+A linked identity for an authenticated user — one record per
+identity-provider account. The same `User` may have several `Identity`
+rows (e.g. a Google sign-in and a separately-enrolled email/password).
+"""
+type Identity {
+  """Unique identifier for this identity record."""
+  id: ID!
+  """The identity provider that issued this identity."""
+  provider: IdentityProvider!
+  """
+  Email address associated with this identity, as reported by the provider.
+  """
+  email: String
+  """
+  Provider-specific metadata blob (claims, profile fields). Shape varies by provider.
+  """
+  identityData: JSON
+  """When this identity was created."""
+  createdAt: DateTime!
+  """When the user last signed in with this identity."""
+  lastSignInAt: DateTime
+}
+```
+
+### `MfaFactor`
+
+```graphql
+"""
+An MFA factor enrolled by a user: an authenticator app holding a TOTP
+secret.
+
+A user may have multiple enrolled factors; `mfaChallengeCreate` selects
+which factor to challenge against. Unenrolment is via `mfaFactorUnenroll`;
+removing a `VERIFIED` factor needs an `AAL2` session, and removing the last
+one leaves an MFA-required user gated to setup on their next request.
+"""
+type MfaFactor {
+  """Unique identifier for this MFA factor."""
+  id: ID!
+  """The type of MFA factor."""
+  factorType: MfaFactorType!
+  """
+  Whether the user has completed the initial verification flow for this factor.
+  """
+  status: MfaFactorStatus!
+  """User-assigned name for this factor (e.g. "Work phone")."""
+  friendlyName: String
+  """When this factor was enrolled."""
+  createdAt: DateTime!
+}
+```
+
+### `MfaTotpEnrollment`
+
+```graphql
+"""
+What an authenticator app needs to add a newly enrolled TOTP factor. Shown
+once, by `mfaFactorEnroll`; the secret is never returned again.
+"""
+type MfaTotpEnrollment {
+  """
+  SVG markup of the QR code that encodes `uri`, for scanning with an authenticator app.
+  """
+  qrCode: String!
+  """The base32 secret, for typing into an authenticator that cannot scan."""
+  secret: String!
+  """The `otpauth://` URI the QR code encodes."""
+  uri: String!
+}
+```
+
+### `MfaRequirementReason`
+
+```graphql
+"""Why a user must hold a verified second factor."""
+enum MfaRequirementReason {
+  """The user is a super admin or a client manager."""
+  STAFF
+  """The user belongs to an organisation whose `requireMfa` setting is on."""
+  ORGANIZATION
+}
+```
+
+### `UserMfaStatus`
+
+```graphql
+"""
+Where a user stands against the multi-factor authentication policy.
+`required` and `reason` come from the policy (staff status and organisation
+membership); `enrolled` is whether a `VERIFIED` TOTP factor exists;
+`satisfied` is whether the requirement is met by the token this status was
+read with: not required, or a session at `AAL2`.
+"""
+type UserMfaStatus {
+  """Whether the user must hold an `AAL2` session to use guarded fields."""
+  required: Boolean!
+  """Why the user is required; null when `required` is false."""
+  reason: MfaRequirementReason
+  """Whether the user holds at least one `VERIFIED` TOTP factor."""
+  enrolled: Boolean!
+  """
+  Whether the requirement is met by the session this status was read with.
+  """
+  satisfied: Boolean!
+}
+```
+
+### `User`
+
+```graphql
+"""
+The authenticated end-user. Returned by the `user` query when a valid
+`Authorization: Bearer <jwt>` header is present; otherwise the field
+resolves to null.
+
+Carries the user's identifiers, all linked identity providers, all
+enrolled MFA factors, where the user stands against the MFA policy, and
+convenience navigation into the user's pending invitations and joined
+organisations. The `appMetadata` blob is server-managed and read-only;
+`userMetadata` is user-editable.
+
+The `user` query is exempt from the MFA policy so a gated user can read
+their status; `invitations` and `organizations` are enforced fields, so
+they error with `MFA_REQUIRED` for a user the policy gates.
+"""
+type User {
+  """Unique user identifier (Supabase Auth `auth.users.id`)."""
+  id: ID!
+  """
+  User's primary email address. Null only for users created via certain admin paths without a confirmed email.
+  """
+  email: String
+  """When the user's email was confirmed (null if still pending)."""
+  emailConfirmedAt: DateTime
+  """User's phone number (E.164 format), if added via MFA or admin path."""
+  phone: String
+  """When the user's phone was confirmed (null if unverified)."""
+  phoneConfirmedAt: DateTime
+  """All identities linked to this user (one per `IdentityProvider`)."""
+  identities: [Identity!]!
+  """All TOTP factors enrolled by this user, verified or not."""
+  mfaFactors: [MfaFactor!]!
+  """Where this user stands against the multi-factor authentication policy."""
+  mfa: UserMfaStatus!
+  """
+  Whether this user has chosen a password. False for an account created by a
+  one-time code, an invitation or Google until `passwordUpdate` sets one.
+  """
+  passwordSet: Boolean!
+  """
+  Server-managed metadata (provider claims, role flags). Read-only from the user's perspective.
+  """
+  appMetadata: JSON
+  """User-editable metadata (display name, preferences). Free-form JSON."""
+  userMetadata: JSON
+  """When this user account was created."""
+  createdAt: DateTime!
+  """When this user account was last updated."""
+  updatedAt: DateTime!
+  """
+  Pending organisation invitations addressed to this user's email. Held to the MFA policy.
+  """
+  invitations(first: Int, after: String): ViewerInvitationConnection! @auth
+  """
+  Organisations this user is a member of. Filter by name with `search`
+  (case-insensitive substring) and order with `sortKey` (default `NAME`) plus
+  `reverse`. Held to the MFA policy.
+  """
+  organizations(first: Int, after: String, search: String, sortKey: OrganizationSortKeys = NAME, reverse: Boolean = false): OrganizationConnection! @auth
+}
+```
+
+### `Session`
+
+```graphql
+"""
+A successfully-authenticated session. Returned by every auth flow that
+produces a usable JWT (`sessionCreate`, `accountVerifyEmail`,
+`magicLinkVerify`, `mfaChallengeVerify`, etc.).
+
+Pass `accessToken` in the `Authorization: Bearer <token>` header on
+subsequent requests. When `accessToken` is near expiry, exchange
+`refreshToken` for a fresh session via `sessionRefresh`. Sessions also
+carry the current authenticator assurance level, decoded from
+`accessToken`, and `user.mfa` says whether that level is enough.
+"""
+type Session {
+  """JWT access token for authenticating API requests."""
+  accessToken: String!
+  """
+  Refresh token used to obtain a new access token. Single-use; rotates on every refresh.
+  """
+  refreshToken: String!
+  """
+  When the access token expires (Supabase Auth issues 1-hour tokens by default).
+  """
+  expiresAt: DateTime!
+  """The authenticated user."""
+  user: User!
+  """
+  Current authenticator assurance level of this session, decoded from `accessToken`.
+  """
+  aal: AuthenticatorAssuranceLevel!
+}
+```
+
+### `SessionStartMethod`
+
+```graphql
+"""
+How the user finishes an email-first sign-in started by `sessionStart`.
+"""
+enum SessionStartMethod {
+  """
+  The account has set a password: call `sessionCreate` with it. No email was sent.
+  """
+  PASSWORD
+  """
+  A sign-in email carrying a six-digit code and a link was sent to the address,
+  if it has an account. Finish with `magicLinkVerify`, or by following the link.
+  An address with no account also answers `EMAIL_CODE`, and is sent nothing.
+  """
+  EMAIL_CODE
+}
+```
+
+### `SessionStartInput`
+
+```graphql
+"""
+Input for `sessionStart` — begin signing in with an email address alone.
+"""
+input SessionStartInput {
+  """Email address of the user."""
+  email: String!
+  """
+  URL the emailed sign-in link returns to (must match a registered redirect URL).
+  """
+  redirectUrl: String
+}
+```
+
+### `SessionStartPayload`
+
+```graphql
+"""
+Payload returned by `sessionStart`.
+
+`method` says which step completes the sign-in, and reveals whether a registered
+address has set a password. An address without a password and an unknown address
+both answer `EMAIL_CODE`, though the response time can differ because only a
+registered address is sent an email.
+"""
+type SessionStartPayload {
+  """How the user finishes signing in."""
+  method: SessionStartMethod!
+}
+```
+
+### `SessionCreateInput`
+
+```graphql
+"""Input for `sessionCreate` — sign in with email and password."""
+input SessionCreateInput {
+  """Email address of the user."""
+  email: String!
+  """Password for the user account."""
+  password: String!
+}
+```
+
+### `SessionCreatePayload`
+
+```graphql
+"""
+Payload returned by `sessionCreate`.
+
+The session is always at `AAL1`. Read `session.user.mfa`: when `required`
+or `enrolled` is true, complete sign-in with `mfaChallengeCreate` and
+`mfaChallengeVerify` (or `mfaFactorEnroll` first when nothing is enrolled)
+before calling guarded fields.
+"""
+type SessionCreatePayload {
+  """The created session."""
+  session: Session
+}
+```
+
+### `SessionRefreshInput`
+
+```graphql
+"""
+Input for `sessionRefresh` — exchange a refresh token for a fresh session.
+"""
+input SessionRefreshInput {
+  """Refresh token from the current session."""
+  refreshToken: String!
+}
+```
+
+### `SessionRefreshPayload`
+
+```graphql
+"""Payload returned by `sessionRefresh`."""
+type SessionRefreshPayload {
+  """
+  The refreshed session, with a new `accessToken` and rotated `refreshToken`.
+  """
+  session: Session
+}
+```
+
+### `AccountCreateInput`
+
+```graphql
+"""
+Input for `accountCreate` — register with an email address.
+
+Registration collects no password. The API creates the account with a
+password it generates and never returns, and the user chooses their own
+password after confirming the address.
+"""
+input AccountCreateInput {
+  """Email address for the new account."""
+  email: String!
+  """
+  URL the confirmation link returns to. Must match a registered redirect URL;
+  Supabase falls back to the site URL when it does not.
+  """
+  redirectUrl: String
+  """Optional metadata to attach to the user's `userMetadata` blob."""
+  metadata: JSON
+}
+```
+
+### `AccountCreatePayload`
+
+```graphql
+"""
+Payload returned by `accountCreate`.
+
+`success` is true for every address that was emailed, so the payload reveals
+nothing about whether the address already has an account. A new or unconfirmed
+address is emailed a confirmation code and link; an address that already
+belongs to a confirmed account is emailed a magic-link sign-in instead. An
+address emailed inside Supabase Auth's minimum send interval also returns
+true — the previous email's code and link are still valid.
+
+Registration completes when the user confirms the address and sets a password
+through `passwordUpdate`.
+"""
+type AccountCreatePayload {
+  """Whether an email was sent to the address."""
+  success: Boolean!
+}
+```
+
+### `AccountVerifyEmailInput`
+
+```graphql
+"""
+Input for `accountVerifyEmail` — exchange a verification token for a session.
+"""
+input AccountVerifyEmailInput {
+  """Email address being verified."""
+  email: String!
+  """Verification token from the confirmation email link."""
+  token: String!
+}
+```
+
+### `AccountVerifyEmailPayload`
+
+```graphql
+"""Payload returned by `accountVerifyEmail`."""
+type AccountVerifyEmailPayload {
+  """Session for the verified user."""
+  session: Session
+}
+```
+
+### `AccountResendVerificationInput`
+
+```graphql
+"""
+Input for `accountResendVerification` — resend the verification email to the same address.
+"""
+input AccountResendVerificationInput {
+  """Email address to resend verification to."""
+  email: String!
+}
+```
+
+### `AccountResendVerificationPayload`
+
+```graphql
+"""Payload returned by `accountResendVerification`."""
+type AccountResendVerificationPayload {
+  """Whether the verification email was sent successfully."""
+  success: Boolean!
+}
+```
+
+### `OAuthAuthorizeInput`
+
+```graphql
+"""
+Input for `oauthAuthorize` — request the upstream provider's authorisation URL.
+"""
+input OAuthAuthorizeInput {
+  """OAuth provider to authorise with."""
+  provider: OAuthProvider!
+  """
+  URL the OAuth provider should redirect the user to after authentication.
+  The server resolves the tenant from this URL's hostname; unknown
+  hostnames fall back to the default tenant.
+  """
+  redirectUrl: String!
+  """
+  Optional scopes to request from the provider, in addition to the defaults.
+  """
+  scopes: [String!]
+}
+```
+
+### `OAuthAuthorizePayload`
+
+```graphql
+"""Payload returned by `oauthAuthorize`."""
+type OAuthAuthorizePayload {
+  """URL to redirect the user to for authorisation."""
+  url: String
+}
+```
+
+### `OAuthCallbackInput`
+
+```graphql
+"""
+Input for `oauthCallback` — exchange the provider's authorisation code for a session.
+"""
+input OAuthCallbackInput {
+  """OAuth provider that initiated the callback."""
+  provider: OAuthProvider!
+  """Authorisation code from the provider's redirect."""
+  code: String!
+}
+```
+
+### `OAuthCallbackPayload`
+
+```graphql
+"""Payload returned by `oauthCallback`."""
+type OAuthCallbackPayload {
+  """Session for the authenticated user."""
+  session: Session
+}
+```
+
+### `OAuthConsentClient`
+
+```graphql
+"""
+OAuth client info returned with an in-flight consent authorisation request.
+"""
+type OAuthConsentClient {
+  """Client ID assigned to the OAuth client."""
+  id: String!
+  """Display name of the OAuth client."""
+  name: String!
+  """Client URI (the application's homepage)."""
+  uri: String
+  """Logo image URL — shown on the consent prompt."""
+  logoUri: String
+}
+```
+
+### `OAuthConsentDetails`
+
+```graphql
+"""
+Details of an in-flight OAuth consent authorisation request. Returned by
+`oauthConsentDetails` when the dashboard renders the consent prompt; the
+client uses `oauthConsentApprove` or `oauthConsentDeny` to resolve it.
+"""
+type OAuthConsentDetails {
+  """
+  Authorisation ID — supply this to `oauthConsentApprove` / `oauthConsentDeny`.
+  """
+  authorizationId: String!
+  """The requesting client (the OAuth app the user is granting access to)."""
+  client: OAuthConsentClient!
+  """Signed-in user's email — shown for confirmation on the consent prompt."""
+  userEmail: String!
+  """Space-separated scopes the client is requesting."""
+  scope: String!
+  """Always `null`. Read `OAuthConsentDetailsPayload.redirectUrl` instead"""
+  redirectUrl: String @deprecated(reason: "Use OAuthConsentDetailsPayload.redirectUrl.")
+}
+```
+
+### `OAuthConsentDetailsInput`
+
+```graphql
+"""Input for `oauthConsentDetails`."""
+input OAuthConsentDetailsInput {
+  """The `authorization_id` query parameter from the consent URL."""
+  authorizationId: String!
+}
+```
+
+### `OAuthConsentDetailsPayload`
+
+```graphql
+"""
+Payload returned by `oauthConsentDetails`. Exactly one of the two fields is set.
+
+`details` is set when the user has not yet consented to this client: render the
+consent prompt, then call `oauthConsentApprove` or `oauthConsentDeny`.
+
+`redirectUrl` is set when the user has already consented to this client for
+these scopes. Reading the authorisation approves it — the authorisation code is
+already minted and the prompt must be skipped. Send the user to this URL.
+"""
+type OAuthConsentDetailsPayload {
+  """
+  Authorisation details — the requesting client and requested scopes. Null when `redirectUrl` is set.
+  """
+  details: OAuthConsentDetails
+  """
+  Where to send the user when consent was already granted. Null when `details` is set.
+  """
+  redirectUrl: String
+}
+```
+
+### `OAuthConsentApproveInput`
+
+```graphql
+"""Input for `oauthConsentApprove`."""
+input OAuthConsentApproveInput {
+  """The `authorization_id` to approve."""
+  authorizationId: String!
+}
+```
+
+### `OAuthConsentDenyInput`
+
+```graphql
+"""Input for `oauthConsentDeny`."""
+input OAuthConsentDenyInput {
+  """The `authorization_id` to deny."""
+  authorizationId: String!
+}
+```
+
+### `OAuthConsentActionPayload`
+
+```graphql
+"""Payload returned by `oauthConsentApprove` and `oauthConsentDeny`."""
+type OAuthConsentActionPayload {
+  """URL to redirect the user to after the consent decision."""
+  redirectUrl: String!
+}
+```
+
+### `MagicLinkSendInput`
+
+```graphql
+"""
+Input for `magicLinkSend` — send a one-time sign-in link to the given email.
+"""
+input MagicLinkSendInput {
+  """Email address to send the magic link to."""
+  email: String!
+  """
+  URL to redirect to after verification (must match a registered redirect URL).
+  """
+  redirectUrl: String
+}
+```
+
+### `MagicLinkSendPayload`
+
+```graphql
+"""Payload returned by `magicLinkSend`."""
+type MagicLinkSendPayload {
+  """Whether the magic link was sent successfully."""
+  success: Boolean!
+}
+```
+
+### `MagicLinkVerifyInput`
+
+```graphql
+"""
+Input for `magicLinkVerify` — exchange the magic-link token for a session.
+"""
+input MagicLinkVerifyInput {
+  """Email address the magic link was sent to."""
+  email: String!
+  """Six-digit code from the email."""
+  token: String!
+}
+```
+
+### `MagicLinkVerifyPayload`
+
+```graphql
+"""Payload returned by `magicLinkVerify`."""
+type MagicLinkVerifyPayload {
+  """Session for the authenticated user."""
+  session: Session
+}
+```
+
+### `EmailLinkType`
+
+```graphql
+"""
+The emails whose link signs the recipient in through `emailLinkVerify`.
+"""
+enum EmailLinkType {
+  """A password-reset email."""
+  RECOVERY
+  """An invitation to an organisation, sent to an address with no account."""
+  INVITE
+  """A sign-in email to a confirmed account."""
+  MAGIC_LINK
+  """A confirmation email for a new registration."""
+  SIGNUP
+}
+```
+
+### `EmailLinkVerifyInput`
+
+```graphql
+"""
+Input for `emailLinkVerify` — exchange the token hash from an emailed link for a session.
+"""
+input EmailLinkVerifyInput {
+  """The `token_hash` carried by the emailed link."""
+  tokenHash: String!
+  """Which email the link came from."""
+  type: EmailLinkType!
+}
+```
+
+### `EmailLinkVerifyPayload`
+
+```graphql
+"""Payload returned by `emailLinkVerify`."""
+type EmailLinkVerifyPayload {
+  """Session for the authenticated user."""
+  session: Session
+}
+```
+
+### `PasswordResetSendInput`
+
+```graphql
+"""
+Input for `passwordResetSend` — send a password-reset email to the given address.
+"""
+input PasswordResetSendInput {
+  """Email address to send the password-reset email to."""
+  email: String!
+  """URL to redirect the user to for the password-reset form."""
+  redirectUrl: String
+}
+```
+
+### `PasswordResetSendPayload`
+
+```graphql
+"""Payload returned by `passwordResetSend`."""
+type PasswordResetSendPayload {
+  """Whether the password-reset email was sent successfully."""
+  success: Boolean!
+}
+```
+
+### `PasswordUpdateInput`
+
+```graphql
+"""
+Input for `passwordUpdate` — change the authenticated user's password.
+The current password is not required; the operation is gated by an
+authenticated session instead.
+
+Updating the password ends every other active session for this user. The
+caller's own session stays valid at the assurance level it holds.
+"""
+input PasswordUpdateInput {
+  """New password to set. Must meet Supabase Auth strength requirements."""
+  newPassword: String!
+}
+```
+
+### `PasswordUpdatePayload`
+
+```graphql
+"""Payload returned by `passwordUpdate`."""
+type PasswordUpdatePayload {
+  """Whether the password was updated successfully."""
+  success: Boolean!
+  """Null: the caller's own session stays valid through the change."""
+  session: Session
+}
+```
+
+### `MfaFactorEnrollInput`
+
+```graphql
+"""
+Input for `mfaFactorEnroll` — enrol an authenticator app. The caller's
+unverified TOTP factors are deleted first, except the two newest enrolled in the
+last minute, which setups open elsewhere may still be showing. An unverified
+factor that holds the `friendlyName` given is deleted however new it is.
+"""
+input MfaFactorEnrollInput {
+  """
+  Name for the factor, shown on the account page. Defaults to "Authenticator app",
+  numbered ("Authenticator app 2", …) past the names the caller's factors hold.
+  """
+  friendlyName: String
+}
+```
+
+### `MfaFactorEnrollPayload`
+
+```graphql
+"""Payload returned by `mfaFactorEnroll`."""
+type MfaFactorEnrollPayload {
+  """The newly enrolled MFA factor (status starts as `UNVERIFIED`)."""
+  factor: MfaFactor!
+  """What the authenticator app needs to add the factor. Shown once."""
+  totp: MfaTotpEnrollment!
+}
+```
+
+### `MfaChallengeCreateInput`
+
+```graphql
+"""
+Input for `mfaChallengeCreate` — open a challenge against an enrolled factor.
+"""
+input MfaChallengeCreateInput {
+  """ID of the MFA factor to challenge."""
+  factorId: ID!
+}
+```
+
+### `MfaChallengeCreatePayload`
+
+```graphql
+"""Payload returned by `mfaChallengeCreate`."""
+type MfaChallengeCreatePayload {
+  """ID of the created challenge — supply to `mfaChallengeVerify`."""
+  challengeId: ID!
+  """When the challenge stops accepting codes."""
+  expiresAt: DateTime!
+}
+```
+
+### `MfaChallengeVerifyInput`
+
+```graphql
+"""
+Input for `mfaChallengeVerify` — submit the current code from the authenticator app.
+"""
+input MfaChallengeVerifyInput {
+  """ID of the MFA factor."""
+  factorId: ID!
+  """ID of the challenge to verify."""
+  challengeId: ID!
+  """Six-digit code from the authenticator app."""
+  code: String!
+}
+```
+
+### `MfaChallengeVerifyPayload`
+
+```graphql
+"""
+Payload returned by `mfaChallengeVerify`. The returned session carries rotated
+tokens at `AAL2`; the user's other sessions are left alone.
+"""
+type MfaChallengeVerifyPayload {
+  """Session upgraded to AAL2, with new `accessToken` and `refreshToken`."""
+  session: Session
+}
+```
+
+### `MfaFactorUnenrollInput`
+
+```graphql
+"""
+Input for `mfaFactorUnenroll` — remove an enrolled MFA factor. Removing a
+`VERIFIED` factor needs an `AAL2` session; an `AAL1` session is refused with
+`MFA_REQUIRED`.
+"""
+input MfaFactorUnenrollInput {
+  """ID of the MFA factor to unenrol."""
+  factorId: ID!
+}
+```
+
+### `MfaFactorUnenrollPayload`
+
+```graphql
+"""Payload returned by `mfaFactorUnenroll`."""
+type MfaFactorUnenrollPayload {
+  """Whether the factor was unenrolled successfully."""
+  success: Boolean!
+}
+```