picked 0.0.101 → 0.0.102-next.2

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

@@ -6,13 +6,14 @@ 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.
+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`.
+Reads the signed-in user. Null when the caller is an API key or the auth service rejects the token.
+Exempt from the MFA policy, so a user the policy gates can read `mfa` and `mfaFactors`.
 
 ```graphql
 user: User @auth(mfa: EXEMPT)
@@ -20,7 +21,8 @@ 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.
+Lists the scopes the caller holds outside any organisation, such as `ORGANIZATION_CREATE`. Empty
+for an API key. `Organization.viewerScopes` lists the scopes held in one organisation.
 
 ```graphql
 viewerScopes: [Scope!]! @auth
@@ -28,7 +30,8 @@ viewerScopes: [Scope!]! @auth
 
 ### `oauthConsentDetails`
 
-Get OAuth consent authorisation details. Requires authentication (USER token only).
+Reads an OAuth authorisation request waiting for the signed-in user's consent. Reading a request
+the user already consented to approves it.
 
 ```graphql
 oauthConsentDetails(input: OAuthConsentDetailsInput!): OAuthConsentDetailsPayload! @auth(only: USER)
@@ -38,10 +41,9 @@ oauthConsentDetails(input: OAuthConsentDetailsInput!): OAuthConsentDetailsPayloa
 
 ### `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.
+Begins a sign-in from an email address alone: answers `PASSWORD`, or emails a sign-in code and
+answers `EMAIL_CODE`. Never creates an account. Returns `RATE_LIMITED` past 10 requests a minute
+from one IP address, or when the project's email quota is spent.
 
 ```graphql
 sessionStart(input: SessionStartInput!): SessionStartPayload!
@@ -49,7 +51,7 @@ sessionStart(input: SessionStartInput!): SessionStartPayload!
 
 ### `sessionCreate`
 
-Create a new session by signing in with email and password.
+Signs in with an email address and password and returns an `AAL1` session.
 
 ```graphql
 sessionCreate(input: SessionCreateInput!): SessionCreatePayload!
@@ -57,7 +59,7 @@ sessionCreate(input: SessionCreateInput!): SessionCreatePayload!
 
 ### `sessionRefresh`
 
-Refresh an existing session using a refresh token.
+Exchanges a refresh token for a new session.
 
 ```graphql
 sessionRefresh(input: SessionRefreshInput!): SessionRefreshPayload!
@@ -65,7 +67,9 @@ sessionRefresh(input: SessionRefreshInput!): SessionRefreshPayload!
 
 ### `accountCreate`
 
-Register an email address and send it a confirmation email.
+Registers an email address and emails it a confirmation code and link. The response does not
+reveal whether the address has an account. Returns `RATE_LIMITED` when the project's email quota
+is spent.
 
 ```graphql
 accountCreate(input: AccountCreateInput!): AccountCreatePayload!
@@ -73,7 +77,7 @@ accountCreate(input: AccountCreateInput!): AccountCreatePayload!
 
 ### `accountVerifyEmail`
 
-Verify a user's email address with a confirmation token.
+Verifies the six-digit code from a confirmation or sign-in email and creates a session.
 
 ```graphql
 accountVerifyEmail(input: AccountVerifyEmailInput!): AccountVerifyEmailPayload!
@@ -81,7 +85,9 @@ accountVerifyEmail(input: AccountVerifyEmailInput!): AccountVerifyEmailPayload!
 
 ### `accountResendVerification`
 
-Resend the email verification link.
+Emails an existing account a new code and link: a confirmation, or a sign-in for a confirmed
+account. An address with no account returns an error, so the response reveals whether an account
+exists. An address emailed within the minimum send interval returns `RATE_LIMITED`.
 
 ```graphql
 accountResendVerification(input: AccountResendVerificationInput!): AccountResendVerificationPayload!
@@ -89,7 +95,7 @@ accountResendVerification(input: AccountResendVerificationInput!): AccountResend
 
 ### `oauthAuthorize`
 
-Initiate an OAuth authorisation flow.
+Creates the provider URL that starts a sign-in with an OAuth provider.
 
 ```graphql
 oauthAuthorize(input: OAuthAuthorizeInput!): OAuthAuthorizePayload!
@@ -97,7 +103,7 @@ oauthAuthorize(input: OAuthAuthorizeInput!): OAuthAuthorizePayload!
 
 ### `oauthCallback`
 
-Handle the OAuth callback and create a session.
+Exchanges the authorisation code from an OAuth provider's redirect for a session.
 
 ```graphql
 oauthCallback(input: OAuthCallbackInput!): OAuthCallbackPayload!
@@ -105,7 +111,7 @@ oauthCallback(input: OAuthCallbackInput!): OAuthCallbackPayload!
 
 ### `oauthConsentApprove`
 
-Approve an OAuth consent request. Requires authentication.
+Approves an OAuth authorisation request for the signed-in user.
 
 ```graphql
 oauthConsentApprove(input: OAuthConsentApproveInput!): OAuthConsentActionPayload! @auth(only: USER)
@@ -113,7 +119,7 @@ oauthConsentApprove(input: OAuthConsentApproveInput!): OAuthConsentActionPayload
 
 ### `oauthConsentDeny`
 
-Deny an OAuth consent request. Requires authentication.
+Denies an OAuth authorisation request for the signed-in user.
 
 ```graphql
 oauthConsentDeny(input: OAuthConsentDenyInput!): OAuthConsentActionPayload! @auth(only: USER)
@@ -121,8 +127,8 @@ oauthConsentDeny(input: OAuthConsentDenyInput!): OAuthConsentActionPayload! @aut
 
 ### `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.
+Emails 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!
@@ -130,7 +136,7 @@ magicLinkSend(input: MagicLinkSendInput!): MagicLinkSendPayload!
 
 ### `magicLinkVerify`
 
-Verify the code from a sign-in or confirmation email and create a session.
+Verifies the six-digit code from a sign-in or confirmation email and creates a session.
 
 ```graphql
 magicLinkVerify(input: MagicLinkVerifyInput!): MagicLinkVerifyPayload!
@@ -138,10 +144,9 @@ 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.
+Verifies the link from a password-reset, invitation, sign-in or confirmation email and creates a
+session. The link works once: call this when the recipient confirms, never on opening the link,
+which an email security scanner may do before delivery.
 
 ```graphql
 emailLinkVerify(input: EmailLinkVerifyInput!): EmailLinkVerifyPayload!
@@ -149,7 +154,8 @@ emailLinkVerify(input: EmailLinkVerifyInput!): EmailLinkVerifyPayload!
 
 ### `passwordResetSend`
 
-Send a password reset email.
+Sends a password-reset email. Returns `RATE_LIMITED` when the address was emailed within the
+minimum send interval or the project's email quota is spent.
 
 ```graphql
 passwordResetSend(input: PasswordResetSendInput!): PasswordResetSendPayload!
@@ -157,9 +163,9 @@ 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`.
+Sets the signed-in user's password without asking for the current one. Ends the user's other
+sessions and keeps the caller's. An `AAL1` session may set a password only while the user holds
+no verified factor, and otherwise gets `MFA_REQUIRED`.
 
 ```graphql
 passwordUpdate(input: PasswordUpdateInput!): PasswordUpdatePayload! @auth(mfa: EXEMPT)
@@ -167,7 +173,9 @@ passwordUpdate(input: PasswordUpdateInput!): PasswordUpdatePayload! @auth(mfa: E
 
 ### `mfaFactorEnroll`
 
-Enrol an authenticator app for the caller. Requires a user session; exempt from the MFA policy.
+Enrols an authenticator app for the caller and returns its secret, once. First deletes the
+caller's unverified factors, except the two newest enrolled in the last minute; one holding the
+given `friendlyName` is deleted however new.
 
 ```graphql
 mfaFactorEnroll(input: MfaFactorEnrollInput!): MfaFactorEnrollPayload! @auth(only: USER, mfa: EXEMPT)
@@ -175,7 +183,7 @@ mfaFactorEnroll(input: MfaFactorEnrollInput!): MfaFactorEnrollPayload! @auth(onl
 
 ### `mfaChallengeCreate`
 
-Open a challenge against one of the caller's factors. Requires a user session; exempt from the MFA policy.
+Opens a challenge against one of the caller's factors.
 
 ```graphql
 mfaChallengeCreate(input: MfaChallengeCreateInput!): MfaChallengeCreatePayload! @auth(only: USER, mfa: EXEMPT)
@@ -183,7 +191,9 @@ mfaChallengeCreate(input: MfaChallengeCreateInput!): MfaChallengeCreatePayload!
 
 ### `mfaChallengeVerify`
 
-Verify a code against a challenge and lift the caller's session to `AAL2`. Requires a user session; exempt from the MFA policy.
+Verifies an authenticator code against a challenge and returns the caller's session at `AAL2`.
+The user's other sessions keep their level. A wrong code returns `MFA_CHALLENGE_FAILED`, and an
+expired challenge `TOKEN_EXPIRED`.
 
 ```graphql
 mfaChallengeVerify(input: MfaChallengeVerifyInput!): MfaChallengeVerifyPayload! @auth(only: USER, mfa: EXEMPT)
@@ -191,7 +201,9 @@ mfaChallengeVerify(input: MfaChallengeVerifyInput!): MfaChallengeVerifyPayload!
 
 ### `mfaFactorUnenroll`
 
-Remove one of the caller's factors. Requires a user session; exempt from the MFA policy, though removing a verified factor needs `AAL2`.
+Removes one of the caller's factors. Removing a verified factor needs an `AAL2` session, and
+otherwise returns `MFA_REQUIRED`. A user the MFA policy requires cannot remove their last verified
+factor (`VALIDATION_ERROR`).
 
 ```graphql
 mfaFactorUnenroll(input: MfaFactorUnenrollInput!): MfaFactorUnenrollPayload! @auth(only: USER, mfa: EXEMPT)
@@ -203,54 +215,37 @@ mfaFactorUnenroll(input: MfaFactorUnenrollInput!): MfaFactorUnenrollPayload! @au
 
 ```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.
+The code in `extensions.code` of an error an auth operation returns. Branch on the code, not on
+the message.
 """
 enum AuthErrorCode {
-  """The provided credentials are invalid (wrong password, unknown email)."""
+  """The email address or password is wrong."""
   INVALID_CREDENTIALS
-  """
-  The user's email address has not yet been confirmed via the verification link.
-  """
+  """The email address is not confirmed."""
   EMAIL_NOT_CONFIRMED
-  """No user was found matching the provided criteria."""
+  """No user matches."""
   USER_NOT_FOUND
-  """A user with the provided email already exists."""
+  """A user with the email address already exists."""
   USER_ALREADY_EXISTS
-  """
-  The provided password does not meet the strength requirements enforced by Supabase Auth.
-  """
+  """The password does not meet the strength rules."""
   WEAK_PASSWORD
-  """
-  The provided token is invalid (malformed, signature mismatch, or not issued by this server).
-  """
+  """The token or code is invalid."""
   INVALID_TOKEN
-  """The provided token has expired."""
+  """The token, code or MFA challenge has expired."""
   TOKEN_EXPIRED
-  """
-  The MFA challenge verification failed (wrong code or rejected challenge).
-  """
+  """The authenticator code is wrong, or the challenge was rejected."""
   MFA_CHALLENGE_FAILED
-  """
-  The specified MFA factor was not found, or does not belong to the caller.
-  """
+  """No factor with the ID belongs 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.
+  The operation needs an `AAL2` session: the caller is staff, belongs to an organisation that
+  requires two-factor authentication, or is removing a verified factor or setting a password while
+  holding one. Verify a factor with `mfaChallengeVerify` and retry with the returned session.
   """
   MFA_REQUIRED
-  """
-  An error occurred while exchanging credentials with the upstream OAuth provider.
-  """
+  """The OAuth provider returned an error."""
   OAUTH_PROVIDER_ERROR
-  """
-  Too many requests; the operation has been rate-limited by Supabase Auth.
-  """
+  """Too many requests, or too many emails sent."""
   RATE_LIMITED
 }
 ```
@@ -259,20 +254,13 @@ enum AuthErrorCode {
 
 ```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`.
+How many authentication factors a session has passed, as NIST 800-63 defines the levels. Read from
+the session's access token.
 """
 enum AuthenticatorAssuranceLevel {
-  """Single-factor authentication (password or OAuth only)."""
+  """One factor: a password, an emailed code or an OAuth provider."""
   AAL1
-  """
-  Multi-factor authentication (a verified TOTP code on top of the first factor).
-  """
+  """Two factors: the first factor and a verified authenticator code."""
   AAL2
 }
 ```
@@ -280,15 +268,11 @@ enum AuthenticatorAssuranceLevel {
 ### `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).
-"""
+"""The provider that issued one of a user's identities."""
 enum IdentityProvider {
-  """Email + password authentication."""
+  """Email address."""
   EMAIL
-  """Google OAuth authentication."""
+  """Google."""
   GOOGLE
 }
 ```
@@ -296,12 +280,9 @@ enum IdentityProvider {
 ### `OAuthProvider`
 
 ```graphql
-"""
-OAuth providers supported for end-user authentication. Used by
-`oauthAuthorize` to select the provider URL to redirect the user to.
-"""
+"""An OAuth provider a user can sign in with."""
 enum OAuthProvider {
-  """Google OAuth provider."""
+  """Google."""
   GOOGLE
 }
 ```
@@ -309,12 +290,10 @@ enum OAuthProvider {
 ### `MfaFactorType`
 
 ```graphql
-"""
-MFA factor types. Time-based one-time passwords from an authenticator app are the only kind.
-"""
+"""The kind of an MFA factor."""
 enum MfaFactorType {
   """
-  An authenticator app generating time-based one-time passwords (RFC 6238).
+  An authenticator app that generates time-based one-time codes (RFC 6238).
   """
   TOTP
 }
@@ -324,16 +303,13 @@ enum MfaFactorType {
 
 ```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`.
+Whether an MFA factor has been verified. A factor starts `UNVERIFIED` and becomes `VERIFIED` when
+`mfaChallengeVerify` accepts a code from it.
 """
 enum MfaFactorStatus {
-  """
-  Factor has been enrolled but the user has not yet verified a delivered code.
-  """
+  """Enrolled, with no code verified yet."""
   UNVERIFIED
-  """Factor has been verified and is active."""
+  """Verified and active."""
   VERIFIED
 }
 ```
@@ -341,15 +317,11 @@ enum MfaFactorStatus {
 ### `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.
-"""
+"""Whether a user holds a verified MFA factor."""
 enum MfaState {
-  """The user holds at least one verified MFA factor."""
+  """The user holds at least one verified factor."""
   ENROLLED
-  """The user holds no verified MFA factor."""
+  """The user holds no verified factor."""
   NOT_ENROLLED
 }
 ```
@@ -358,26 +330,24 @@ enum MfaState {
 
 ```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).
+An account at an identity provider that a user signs in with. A user can have several.
 """
 type Identity {
-  """Unique identifier for this identity record."""
+  """The ID of the identity."""
   id: ID!
-  """The identity provider that issued this identity."""
+  """The provider that issued the identity."""
   provider: IdentityProvider!
-  """
-  Email address associated with this identity, as reported by the provider.
-  """
+  """The email address the provider reports. Null when it reports none."""
   email: String
   """
-  Provider-specific metadata blob (claims, profile fields). Shape varies by provider.
+  The claims and profile fields the provider reports. The shape depends on the provider.
   """
   identityData: JSON
-  """When this identity was created."""
+  """When the identity was created."""
   createdAt: DateTime!
-  """When the user last signed in with this identity."""
+  """
+  When the user last signed in with this identity. Null when they never have.
+  """
   lastSignInAt: DateTime
 }
 ```
@@ -386,26 +356,21 @@ type Identity {
 
 ```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.
+An authenticator app a user has enrolled as a second factor. Removing a `VERIFIED` factor needs an
+`AAL2` session, and a user the MFA policy requires cannot remove their last `VERIFIED` factor.
 """
 type MfaFactor {
-  """Unique identifier for this MFA factor."""
+  """The ID of the factor."""
   id: ID!
-  """The type of MFA factor."""
+  """The kind of factor."""
   factorType: MfaFactorType!
+  """Whether the factor has been verified."""
+  status: MfaFactorStatus!
   """
-  Whether the user has completed the initial verification flow for this factor.
+  The name of the factor, shown on the account page. Null when none is set.
   """
-  status: MfaFactorStatus!
-  """User-assigned name for this factor (e.g. "Work phone")."""
   friendlyName: String
-  """When this factor was enrolled."""
+  """When the factor was enrolled."""
   createdAt: DateTime!
 }
 ```
@@ -414,15 +379,13 @@ type MfaFactor {
 
 ```graphql
 """
-What an authenticator app needs to add a newly enrolled TOTP factor. Shown
-once, by `mfaFactorEnroll`; the secret is never returned again.
+What an authenticator app needs to add a new TOTP factor. Returned 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.
-  """
+  """SVG markup of a QR code that encodes `uri`."""
   qrCode: String!
-  """The base32 secret, for typing into an authenticator that cannot scan."""
+  """The base32 secret, for an authenticator that cannot scan."""
   secret: String!
   """The `otpauth://` URI the QR code encodes."""
   uri: String!
@@ -436,7 +399,7 @@ type MfaTotpEnrollment {
 enum MfaRequirementReason {
   """The user is a super admin or a client manager."""
   STAFF
-  """The user belongs to an organisation whose `requireMfa` setting is on."""
+  """The user belongs to an organisation with `requireMfa` on."""
   ORGANIZATION
 }
 ```
@@ -444,22 +407,19 @@ enum MfaRequirementReason {
 ### `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`.
-"""
+"""Where a user stands against the multi-factor authentication policy."""
 type UserMfaStatus {
-  """Whether the user must hold an `AAL2` session to use guarded fields."""
+  """
+  Whether the user must hold an `AAL2` session to use the fields the policy guards.
+  """
   required: Boolean!
-  """Why the user is required; null when `required` is false."""
+  """Why the user is required. Null when `required` is false."""
   reason: MfaRequirementReason
-  """Whether the user holds at least one `VERIFIED` TOTP factor."""
+  """Whether the user holds at least one `VERIFIED` factor."""
   enrolled: Boolean!
   """
-  Whether the requirement is met by the session this status was read with.
+  Whether the session this status was read with meets the requirement: the user is not required,
+  or the session is at `AAL2`.
   """
   satisfied: Boolean!
 }
@@ -469,62 +429,48 @@ type UserMfaStatus {
 
 ```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.
+A signed-in user. `invitations` and `organizations` return `MFA_REQUIRED` for a user the MFA
+policy gates; the other fields stay readable.
 """
 type User {
-  """Unique user identifier (Supabase Auth `auth.users.id`)."""
+  """The ID of the user."""
   id: ID!
-  """
-  User's primary email address. Null only for users created via certain admin paths without a confirmed email.
-  """
+  """The user's primary email address. Null when the account has none."""
   email: String
-  """When the user's email was confirmed (null if still pending)."""
+  """When the user confirmed their email address. Null until confirmed."""
   emailConfirmedAt: DateTime
-  """User's phone number (E.164 format), if added via MFA or admin path."""
+  """The user's phone number, in E.164 format. Null when none is set."""
   phone: String
-  """When the user's phone was confirmed (null if unverified)."""
+  """When the user confirmed their phone number. Null until confirmed."""
   phoneConfirmedAt: DateTime
-  """All identities linked to this user (one per `IdentityProvider`)."""
+  """The identities the user signs in with."""
   identities: [Identity!]!
-  """All TOTP factors enrolled by this user, verified or not."""
+  """The user's MFA factors, verified or not."""
   mfaFactors: [MfaFactor!]!
-  """Where this user stands against the multi-factor authentication policy."""
+  """Where the 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.
+  Whether the user has chosen a password. False for an account created by an emailed 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.
+  Metadata the server manages, such as provider claims and role flags. The user cannot change it.
   """
   appMetadata: JSON
-  """User-editable metadata (display name, preferences). Free-form JSON."""
+  """Metadata the user can change, such as a display name and preferences."""
   userMetadata: JSON
-  """When this user account was created."""
+  """When the user was created."""
   createdAt: DateTime!
-  """When this user account was last updated."""
+  """When the user last changed."""
   updatedAt: DateTime!
   """
-  Pending organisation invitations addressed to this user's email. Held to the MFA policy.
+  The pending organisation invitations addressed to the user's email address.
   """
   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.
+  The organisations the user belongs to; for a staff caller, every organisation. `search` filters
+  by name (case-insensitive substring); `sortKey` and `reverse` set the order.
   """
   organizations(first: Int, after: String, search: String, sortKey: OrganizationSortKeys = NAME, reverse: Boolean = false): OrganizationConnection! @auth
 }
@@ -534,32 +480,20 @@ type User {
 
 ```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.
+The result of a sign-in: an access token, a refresh token, and when the access token expires.
+Send `accessToken` as `Authorization: Bearer <token>`; exchange `refreshToken` through
+`sessionRefresh` for a new session before the access token expires.
 """
 type Session {
-  """JWT access token for authenticating API requests."""
+  """The access token (a JWT) that authenticates API requests."""
   accessToken: String!
-  """
-  Refresh token used to obtain a new access token. Single-use; rotates on every refresh.
-  """
+  """The refresh token. Single-use: `sessionRefresh` returns a new one."""
   refreshToken: String!
-  """
-  When the access token expires (Supabase Auth issues 1-hour tokens by default).
-  """
+  """When the access token expires."""
   expiresAt: DateTime!
-  """The authenticated user."""
+  """The signed-in user."""
   user: User!
-  """
-  Current authenticator assurance level of this session, decoded from `accessToken`.
-  """
+  """The session's assurance level, read from `accessToken`."""
   aal: AuthenticatorAssuranceLevel!
 }
 ```
@@ -567,18 +501,16 @@ type Session {
 ### `SessionStartMethod`
 
 ```graphql
-"""
-How the user finishes an email-first sign-in started by `sessionStart`.
-"""
+"""How a user finishes a sign-in that `sessionStart` began."""
 enum SessionStartMethod {
   """
-  The account has set a password: call `sessionCreate` with it. No email was sent.
+  The account has a password: call `sessionCreate` with it. No email is 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.
+  A six-digit code and a link were emailed to the address, if it has an account. Finish with
+  `magicLinkVerify` or the link. An address with no account also answers `EMAIL_CODE` and is sent
+  nothing.
   """
   EMAIL_CODE
 }
@@ -587,14 +519,12 @@ enum SessionStartMethod {
 ### `SessionStartInput`
 
 ```graphql
-"""
-Input for `sessionStart` — begin signing in with an email address alone.
-"""
+"""The input of `sessionStart`."""
 input SessionStartInput {
-  """Email address of the user."""
+  """The email address to sign in with."""
   email: String!
   """
-  URL the emailed sign-in link returns to (must match a registered redirect URL).
+  The URL the emailed link returns to. Must match a registered redirect URL.
   """
   redirectUrl: String
 }
@@ -604,12 +534,9 @@ input SessionStartInput {
 
 ```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.
+The result of `sessionStart`. `method` reveals whether a registered address has a password. An
+address without one and an unknown address both answer `EMAIL_CODE`, though the response time can
+differ because only a registered address is emailed.
 """
 type SessionStartPayload {
   """How the user finishes signing in."""
@@ -620,11 +547,11 @@ type SessionStartPayload {
 ### `SessionCreateInput`
 
 ```graphql
-"""Input for `sessionCreate` — sign in with email and password."""
+"""The input of `sessionCreate`."""
 input SessionCreateInput {
-  """Email address of the user."""
+  """The user's email address."""
   email: String!
-  """Password for the user account."""
+  """The user's password."""
   password: String!
 }
 ```
@@ -633,15 +560,12 @@ input SessionCreateInput {
 
 ```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.
+The result of `sessionCreate`. The session is at `AAL1`: when `session.user.mfa.required` or
+`enrolled` is true, finish with `mfaChallengeCreate` and `mfaChallengeVerify` (or `mfaFactorEnroll`
+first when nothing is enrolled) before calling guarded fields.
 """
 type SessionCreatePayload {
-  """The created session."""
+  """The new session."""
   session: Session
 }
 ```
@@ -649,11 +573,9 @@ type SessionCreatePayload {
 ### `SessionRefreshInput`
 
 ```graphql
-"""
-Input for `sessionRefresh` — exchange a refresh token for a fresh session.
-"""
+"""The input of `sessionRefresh`."""
 input SessionRefreshInput {
-  """Refresh token from the current session."""
+  """The refresh token of the current session."""
   refreshToken: String!
 }
 ```
@@ -661,11 +583,9 @@ input SessionRefreshInput {
 ### `SessionRefreshPayload`
 
 ```graphql
-"""Payload returned by `sessionRefresh`."""
+"""The result of `sessionRefresh`."""
 type SessionRefreshPayload {
-  """
-  The refreshed session, with a new `accessToken` and rotated `refreshToken`.
-  """
+  """The new session, with a new `accessToken` and `refreshToken`."""
   session: Session
 }
 ```
@@ -674,21 +594,18 @@ type SessionRefreshPayload {
 
 ```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.
+The input of `accountCreate`. Registration takes no password: the user sets one with
+`passwordUpdate` after confirming the address.
 """
 input AccountCreateInput {
-  """Email address for the new account."""
+  """The email address to register."""
   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.
+  The URL the confirmation link returns to. Must match a registered redirect URL; otherwise the
+  link returns to the site URL.
   """
   redirectUrl: String
-  """Optional metadata to attach to the user's `userMetadata` blob."""
+  """Metadata to store in the user's `userMetadata`."""
   metadata: JSON
 }
 ```
@@ -697,20 +614,15 @@ input AccountCreateInput {
 
 ```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`.
+The result of `accountCreate`. The payload is the same whether or not the address has an account:
+a new or unconfirmed address is emailed a confirmation code and link, and a confirmed account a
+sign-in code and link.
 """
 type AccountCreatePayload {
-  """Whether an email was sent to the address."""
+  """
+  Whether the request succeeded. Also true when the address was emailed within the minimum send
+  interval; the earlier email's code and link stay valid.
+  """
   success: Boolean!
 }
 ```
@@ -718,13 +630,11 @@ type AccountCreatePayload {
 ### `AccountVerifyEmailInput`
 
 ```graphql
-"""
-Input for `accountVerifyEmail` — exchange a verification token for a session.
-"""
+"""The input of `accountVerifyEmail`."""
 input AccountVerifyEmailInput {
-  """Email address being verified."""
+  """The email address the code was sent to."""
   email: String!
-  """Verification token from the confirmation email link."""
+  """The six-digit code from the email."""
   token: String!
 }
 ```
@@ -732,9 +642,9 @@ input AccountVerifyEmailInput {
 ### `AccountVerifyEmailPayload`
 
 ```graphql
-"""Payload returned by `accountVerifyEmail`."""
+"""The result of `accountVerifyEmail`."""
 type AccountVerifyEmailPayload {
-  """Session for the verified user."""
+  """The session for the confirmed user."""
   session: Session
 }
 ```
@@ -742,11 +652,9 @@ type AccountVerifyEmailPayload {
 ### `AccountResendVerificationInput`
 
 ```graphql
-"""
-Input for `accountResendVerification` — resend the verification email to the same address.
-"""
+"""The input of `accountResendVerification`."""
 input AccountResendVerificationInput {
-  """Email address to resend verification to."""
+  """The email address to send the code to."""
   email: String!
 }
 ```
@@ -754,9 +662,9 @@ input AccountResendVerificationInput {
 ### `AccountResendVerificationPayload`
 
 ```graphql
-"""Payload returned by `accountResendVerification`."""
+"""The result of `accountResendVerification`."""
 type AccountResendVerificationPayload {
-  """Whether the verification email was sent successfully."""
+  """Whether the email was sent."""
   success: Boolean!
 }
 ```
@@ -764,21 +672,17 @@ type AccountResendVerificationPayload {
 ### `OAuthAuthorizeInput`
 
 ```graphql
-"""
-Input for `oauthAuthorize` — request the upstream provider's authorisation URL.
-"""
+"""The input of `oauthAuthorize`."""
 input OAuthAuthorizeInput {
-  """OAuth provider to authorise with."""
+  """The provider to sign in 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.
+  The URL the provider returns the user to. Its host selects the tenant, and an unknown host
+  selects the default one. Outside `picked.app`, the user returns to the same path on the
+  dashboard's own origin.
   """
   redirectUrl: String!
-  """
-  Optional scopes to request from the provider, in addition to the defaults.
-  """
+  """Provider scopes to request in addition to the defaults."""
   scopes: [String!]
 }
 ```
@@ -786,9 +690,9 @@ input OAuthAuthorizeInput {
 ### `OAuthAuthorizePayload`
 
 ```graphql
-"""Payload returned by `oauthAuthorize`."""
+"""The result of `oauthAuthorize`."""
 type OAuthAuthorizePayload {
-  """URL to redirect the user to for authorisation."""
+  """The provider URL to send the user to."""
   url: String
 }
 ```
@@ -796,13 +700,11 @@ type OAuthAuthorizePayload {
 ### `OAuthCallbackInput`
 
 ```graphql
-"""
-Input for `oauthCallback` — exchange the provider's authorisation code for a session.
-"""
+"""The input of `oauthCallback`."""
 input OAuthCallbackInput {
-  """OAuth provider that initiated the callback."""
+  """The provider that issued the code."""
   provider: OAuthProvider!
-  """Authorisation code from the provider's redirect."""
+  """The authorisation code from the provider's redirect."""
   code: String!
 }
 ```
@@ -810,9 +712,9 @@ input OAuthCallbackInput {
 ### `OAuthCallbackPayload`
 
 ```graphql
-"""Payload returned by `oauthCallback`."""
+"""The result of `oauthCallback`."""
 type OAuthCallbackPayload {
-  """Session for the authenticated user."""
+  """The session for the signed-in user."""
   session: Session
 }
 ```
@@ -820,17 +722,15 @@ type OAuthCallbackPayload {
 ### `OAuthConsentClient`
 
 ```graphql
-"""
-OAuth client info returned with an in-flight consent authorisation request.
-"""
+"""The OAuth client that asks for a user's consent."""
 type OAuthConsentClient {
-  """Client ID assigned to the OAuth client."""
+  """The client ID."""
   id: String!
-  """Display name of the OAuth client."""
+  """The client's display name."""
   name: String!
-  """Client URI (the application's homepage)."""
+  """The client's homepage. Null when not set."""
   uri: String
-  """Logo image URL — shown on the consent prompt."""
+  """The URL of the client's logo. Null when not set."""
   logoUri: String
 }
 ```
@@ -838,23 +738,19 @@ type OAuthConsentClient {
 ### `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.
-"""
+"""An OAuth authorisation request waiting for the user's consent."""
 type OAuthConsentDetails {
   """
-  Authorisation ID — supply this to `oauthConsentApprove` / `oauthConsentDeny`.
+  The ID of the request, for `oauthConsentApprove` or `oauthConsentDeny`.
   """
   authorizationId: String!
-  """The requesting client (the OAuth app the user is granting access to)."""
+  """The client that asks for access."""
   client: OAuthConsentClient!
-  """Signed-in user's email — shown for confirmation on the consent prompt."""
+  """The signed-in user's email address."""
   userEmail: String!
-  """Space-separated scopes the client is requesting."""
+  """The scopes the client asks for, separated by spaces."""
   scope: String!
-  """Always `null`. Read `OAuthConsentDetailsPayload.redirectUrl` instead"""
+  """Always null."""
   redirectUrl: String @deprecated(reason: "Use OAuthConsentDetailsPayload.redirectUrl.")
 }
 ```
@@ -862,9 +758,9 @@ type OAuthConsentDetails {
 ### `OAuthConsentDetailsInput`
 
 ```graphql
-"""Input for `oauthConsentDetails`."""
+"""The input of `oauthConsentDetails`."""
 input OAuthConsentDetailsInput {
-  """The `authorization_id` query parameter from the consent URL."""
+  """The `authorization_id` query parameter of the consent URL."""
   authorizationId: String!
 }
 ```
@@ -873,22 +769,17 @@ input OAuthConsentDetailsInput {
 
 ```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.
+The result of `oauthConsentDetails`. Exactly one field is set: `details` when the user has not
+yet consented to the client for these scopes, and `redirectUrl` when they have. In that case the
+read itself approves the request: skip the prompt and send the user to `redirectUrl`.
 """
 type OAuthConsentDetailsPayload {
   """
-  Authorisation details — the requesting client and requested scopes. Null when `redirectUrl` is set.
+  The request to show on the consent prompt. Null when `redirectUrl` is set.
   """
   details: OAuthConsentDetails
   """
-  Where to send the user when consent was already granted. Null when `details` is set.
+  Where to send the user when consent was already given. Null when `details` is set.
   """
   redirectUrl: String
 }
@@ -897,9 +788,9 @@ type OAuthConsentDetailsPayload {
 ### `OAuthConsentApproveInput`
 
 ```graphql
-"""Input for `oauthConsentApprove`."""
+"""The input of `oauthConsentApprove`."""
 input OAuthConsentApproveInput {
-  """The `authorization_id` to approve."""
+  """The ID of the request to approve."""
   authorizationId: String!
 }
 ```
@@ -907,9 +798,9 @@ input OAuthConsentApproveInput {
 ### `OAuthConsentDenyInput`
 
 ```graphql
-"""Input for `oauthConsentDeny`."""
+"""The input of `oauthConsentDeny`."""
 input OAuthConsentDenyInput {
-  """The `authorization_id` to deny."""
+  """The ID of the request to deny."""
   authorizationId: String!
 }
 ```
@@ -917,9 +808,9 @@ input OAuthConsentDenyInput {
 ### `OAuthConsentActionPayload`
 
 ```graphql
-"""Payload returned by `oauthConsentApprove` and `oauthConsentDeny`."""
+"""The result of `oauthConsentApprove` and `oauthConsentDeny`."""
 type OAuthConsentActionPayload {
-  """URL to redirect the user to after the consent decision."""
+  """Where to send the user after the decision."""
   redirectUrl: String!
 }
 ```
@@ -927,14 +818,12 @@ type OAuthConsentActionPayload {
 ### `MagicLinkSendInput`
 
 ```graphql
-"""
-Input for `magicLinkSend` — send a one-time sign-in link to the given email.
-"""
+"""The input of `magicLinkSend`."""
 input MagicLinkSendInput {
-  """Email address to send the magic link to."""
+  """The email address to send the code to."""
   email: String!
   """
-  URL to redirect to after verification (must match a registered redirect URL).
+  The URL the emailed link returns to. Must match a registered redirect URL.
   """
   redirectUrl: String
 }
@@ -943,9 +832,12 @@ input MagicLinkSendInput {
 ### `MagicLinkSendPayload`
 
 ```graphql
-"""Payload returned by `magicLinkSend`."""
+"""The result of `magicLinkSend`."""
 type MagicLinkSendPayload {
-  """Whether the magic link was sent successfully."""
+  """
+  Always true: an address with no account, or one emailed within the minimum send interval, also
+  answers true.
+  """
   success: Boolean!
 }
 ```
@@ -953,13 +845,11 @@ type MagicLinkSendPayload {
 ### `MagicLinkVerifyInput`
 
 ```graphql
-"""
-Input for `magicLinkVerify` — exchange the magic-link token for a session.
-"""
+"""The input of `magicLinkVerify`."""
 input MagicLinkVerifyInput {
-  """Email address the magic link was sent to."""
+  """The email address the code was sent to."""
   email: String!
-  """Six-digit code from the email."""
+  """The six-digit code from the email."""
   token: String!
 }
 ```
@@ -967,9 +857,9 @@ input MagicLinkVerifyInput {
 ### `MagicLinkVerifyPayload`
 
 ```graphql
-"""Payload returned by `magicLinkVerify`."""
+"""The result of `magicLinkVerify`."""
 type MagicLinkVerifyPayload {
-  """Session for the authenticated user."""
+  """The session for the signed-in user."""
   session: Session
 }
 ```
@@ -977,9 +867,7 @@ type MagicLinkVerifyPayload {
 ### `EmailLinkType`
 
 ```graphql
-"""
-The emails whose link signs the recipient in through `emailLinkVerify`.
-"""
+"""The kind of email a link passed to `emailLinkVerify` came from."""
 enum EmailLinkType {
   """A password-reset email."""
   RECOVERY
@@ -995,13 +883,11 @@ enum EmailLinkType {
 ### `EmailLinkVerifyInput`
 
 ```graphql
-"""
-Input for `emailLinkVerify` — exchange the token hash from an emailed link for a session.
-"""
+"""The input of `emailLinkVerify`."""
 input EmailLinkVerifyInput {
-  """The `token_hash` carried by the emailed link."""
+  """The `token_hash` parameter of the emailed link."""
   tokenHash: String!
-  """Which email the link came from."""
+  """The kind of email the link came from."""
   type: EmailLinkType!
 }
 ```
@@ -1009,9 +895,9 @@ input EmailLinkVerifyInput {
 ### `EmailLinkVerifyPayload`
 
 ```graphql
-"""Payload returned by `emailLinkVerify`."""
+"""The result of `emailLinkVerify`."""
 type EmailLinkVerifyPayload {
-  """Session for the authenticated user."""
+  """The session for the signed-in user."""
   session: Session
 }
 ```
@@ -1019,13 +905,11 @@ type EmailLinkVerifyPayload {
 ### `PasswordResetSendInput`
 
 ```graphql
-"""
-Input for `passwordResetSend` — send a password-reset email to the given address.
-"""
+"""The input of `passwordResetSend`."""
 input PasswordResetSendInput {
-  """Email address to send the password-reset email to."""
+  """The email address to send the reset email to."""
   email: String!
-  """URL to redirect the user to for the password-reset form."""
+  """The URL the reset link returns to, where the user sets a new password."""
   redirectUrl: String
 }
 ```
@@ -1033,9 +917,9 @@ input PasswordResetSendInput {
 ### `PasswordResetSendPayload`
 
 ```graphql
-"""Payload returned by `passwordResetSend`."""
+"""The result of `passwordResetSend`."""
 type PasswordResetSendPayload {
-  """Whether the password-reset email was sent successfully."""
+  """Whether the request succeeded."""
   success: Boolean!
 }
 ```
@@ -1043,16 +927,9 @@ type PasswordResetSendPayload {
 ### `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.
-"""
+"""The input of `passwordUpdate`. Every field is required."""
 input PasswordUpdateInput {
-  """New password to set. Must meet Supabase Auth strength requirements."""
+  """The new password. Must meet the password strength rules."""
   newPassword: String!
 }
 ```
@@ -1060,11 +937,11 @@ input PasswordUpdateInput {
 ### `PasswordUpdatePayload`
 
 ```graphql
-"""Payload returned by `passwordUpdate`."""
+"""The result of `passwordUpdate`."""
 type PasswordUpdatePayload {
-  """Whether the password was updated successfully."""
+  """Whether the password changed."""
   success: Boolean!
-  """Null: the caller's own session stays valid through the change."""
+  """Always null; the caller's session stays valid."""
   session: Session
 }
 ```
@@ -1072,16 +949,11 @@ type PasswordUpdatePayload {
 ### `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.
-"""
+"""The input of `mfaFactorEnroll`."""
 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.
+  The name of 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
 }
@@ -1090,11 +962,15 @@ input MfaFactorEnrollInput {
 ### `MfaFactorEnrollPayload`
 
 ```graphql
-"""Payload returned by `mfaFactorEnroll`."""
+"""
+The result of `mfaFactorEnroll`. `totp` carries the factor's secret, which is returned only here.
+"""
 type MfaFactorEnrollPayload {
-  """The newly enrolled MFA factor (status starts as `UNVERIFIED`)."""
+  """
+  The new factor, `UNVERIFIED` until `mfaChallengeVerify` accepts a code from it.
+  """
   factor: MfaFactor!
-  """What the authenticator app needs to add the factor. Shown once."""
+  """What an authenticator app needs to add the factor."""
   totp: MfaTotpEnrollment!
 }
 ```
@@ -1102,11 +978,9 @@ type MfaFactorEnrollPayload {
 ### `MfaChallengeCreateInput`
 
 ```graphql
-"""
-Input for `mfaChallengeCreate` — open a challenge against an enrolled factor.
-"""
+"""The input of `mfaChallengeCreate`."""
 input MfaChallengeCreateInput {
-  """ID of the MFA factor to challenge."""
+  """The ID of the factor to challenge."""
   factorId: ID!
 }
 ```
@@ -1114,9 +988,9 @@ input MfaChallengeCreateInput {
 ### `MfaChallengeCreatePayload`
 
 ```graphql
-"""Payload returned by `mfaChallengeCreate`."""
+"""The result of `mfaChallengeCreate`."""
 type MfaChallengeCreatePayload {
-  """ID of the created challenge — supply to `mfaChallengeVerify`."""
+  """The ID of the challenge, for `mfaChallengeVerify`."""
   challengeId: ID!
   """When the challenge stops accepting codes."""
   expiresAt: DateTime!
@@ -1126,15 +1000,13 @@ type MfaChallengeCreatePayload {
 ### `MfaChallengeVerifyInput`
 
 ```graphql
-"""
-Input for `mfaChallengeVerify` — submit the current code from the authenticator app.
-"""
+"""The input of `mfaChallengeVerify`."""
 input MfaChallengeVerifyInput {
-  """ID of the MFA factor."""
+  """The ID of the factor."""
   factorId: ID!
-  """ID of the challenge to verify."""
+  """The ID of the challenge."""
   challengeId: ID!
-  """Six-digit code from the authenticator app."""
+  """The six-digit code from the authenticator app."""
   code: String!
 }
 ```
@@ -1142,12 +1014,11 @@ input MfaChallengeVerifyInput {
 ### `MfaChallengeVerifyPayload`
 
 ```graphql
-"""
-Payload returned by `mfaChallengeVerify`. The returned session carries rotated
-tokens at `AAL2`; the user's other sessions are left alone.
-"""
+"""The result of `mfaChallengeVerify`."""
 type MfaChallengeVerifyPayload {
-  """Session upgraded to AAL2, with new `accessToken` and `refreshToken`."""
+  """
+  The caller's session at `AAL2`, with a new `accessToken` and `refreshToken`.
+  """
   session: Session
 }
 ```
@@ -1155,13 +1026,9 @@ type MfaChallengeVerifyPayload {
 ### `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`.
-"""
+"""The input of `mfaFactorUnenroll`."""
 input MfaFactorUnenrollInput {
-  """ID of the MFA factor to unenrol."""
+  """The ID of the factor to remove."""
   factorId: ID!
 }
 ```
@@ -1169,9 +1036,9 @@ input MfaFactorUnenrollInput {
 ### `MfaFactorUnenrollPayload`
 
 ```graphql
-"""Payload returned by `mfaFactorUnenroll`."""
+"""The result of `mfaFactorUnenroll`."""
 type MfaFactorUnenrollPayload {
-  """Whether the factor was unenrolled successfully."""
+  """Whether the factor was removed."""
   success: Boolean!
 }
 ```