feat(sca): SCA management surface — enrollment, login/session, beneficiary trust, 2FA reset

openapi/components/schemas/sca/BeneficiaryTrustConfirm.yaml

@@ -0,0 +1,12 @@
+type: object
+description: >-
+  The result of a confirm-trust / confirm-untrust call. `trusted` is `true`
+  after a successful trust and `false` after a successful untrust.
+required:
+  - trusted
+properties:
+  trusted:
+    type: boolean
+    description: >-
+      Whether the beneficiary is now trusted. `true` after a successful trust,
+      `false` after a successful untrust.

openapi/components/schemas/sca/BeneficiaryTrustConfirmRequest.yaml

@@ -0,0 +1,47 @@
+type: object
+description: >-
+  Confirms trusting or untrusting a beneficiary by submitting the SCA proof.
+  Carries the same proof fields as an `ScaAuthorization` (`code` for `SMS_OTP` /
+  `TOTP`, or `passkeyAssertion` + `origin` for `PASSKEY`), plus the
+  `whitelistedId` returned by the trust start and, when the start issued one,
+  the `challengeId`.
+required:
+  - whitelistedId
+properties:
+  whitelistedId:
+    type: string
+    description: >-
+      The provider beneficiary handle returned as `whitelistedId` by the trust
+      start, threaded back so confirm need not re-whitelist.
+  challengeId:
+    type:
+      - string
+      - 'null'
+    description: >-
+      The challenge handle from the trust start's `scaChallenge`, when one was
+      issued. Omit when the start returned no challenge.
+  code:
+    type:
+      - string
+      - 'null'
+    description: >-
+      The one-time code the customer received by SMS, or read from their
+      authenticator app. Provide for `SMS_OTP` / `TOTP`. In sandbox, the code is
+      always `123456`.
+    example: '123456'
+  passkeyAssertion:
+    type:
+      - object
+      - 'null'
+    additionalProperties: true
+    description: >-
+      Opaque WebAuthn assertion produced by the device from the challenge's
+      assertion options. Required when satisfying a `PASSKEY` challenge.
+  origin:
+    type:
+      - string
+      - 'null'
+    description: >-
+      The WebAuthn origin the `passkeyAssertion` was produced against. Required
+      alongside `passkeyAssertion`; omit it for the `code` path.
+    example: https://app.example.com

openapi/components/schemas/sca/BeneficiaryTrustStart.yaml

@@ -0,0 +1,21 @@
+type: object
+description: >-
+  The provider handle plus the SCA challenge a caller authorizes to finish
+  trusting (or untrusting) a beneficiary. `whitelistedId` is the provider's
+  beneficiary handle; thread it back on the confirm call so confirm need not
+  re-whitelist (which could trigger a second challenge). `scaChallenge` is
+  omitted when the provider does not surface one on the whitelist response; the
+  caller then confirms without a `challengeId`.
+required:
+  - whitelistedId
+properties:
+  whitelistedId:
+    type: string
+    description: >-
+      The provider's beneficiary (whitelist) handle. Thread it back on the
+      confirm call.
+  scaChallenge:
+    $ref: ./ScaChallenge.yaml
+    description: >-
+      The SCA challenge to satisfy on the confirm call. Omitted when the
+      provider issues no challenge on the whitelist response.

openapi/components/schemas/sca/PasskeyEnrollmentConfirmRequest.yaml

@@ -0,0 +1,20 @@
+type: object
+description: >-
+  The WebAuthn credential a device produced for a passkey registration
+  challenge, submitted to enroll the passkey factor.
+required:
+  - origin
+  - credential
+properties:
+  origin:
+    type: string
+    description: >-
+      The WebAuthn origin the `credential` was produced against (one of the
+      enrollment start's `allowedOrigins`).
+    example: https://app.example.com
+  credential:
+    type: object
+    additionalProperties: true
+    description: >-
+      Opaque WebAuthn credential the device produced from the enrollment start's
+      `options`.

openapi/components/schemas/sca/PasskeyEnrollmentConfirmResponse.yaml

@@ -0,0 +1,7 @@
+type: object
+description: The enrolled passkey factor returned after a successful confirmation.
+required:
+  - factor
+properties:
+  factor:
+    $ref: ./ScaFactorView.yaml

openapi/components/schemas/sca/PasskeyEnrollmentStart.yaml

@@ -0,0 +1,31 @@
+type: object
+description: >-
+  Opaque WebAuthn registration options relayed to the end user's device to
+  enroll a passkey factor. Grid performs no crypto; pass `options` to the
+  device's WebAuthn API to produce a credential, then submit that credential to
+  the confirm endpoint unmodified.
+required:
+  - options
+  - allowedOrigins
+  - relyingPartyId
+properties:
+  options:
+    type: object
+    additionalProperties: true
+    description: >-
+      Opaque WebAuthn `PublicKeyCredentialCreationOptions`. Pass to the device's
+      WebAuthn registration API unmodified.
+  allowedOrigins:
+    type: array
+    description: >-
+      The origins the WebAuthn registration ceremony may run against. The origin
+      the credential is produced against must be one of these and must be echoed
+      back on the confirm call.
+    items:
+      type: string
+    example:
+      - https://app.example.com
+  relyingPartyId:
+    type: string
+    description: The WebAuthn relying-party id the credential is bound to.
+    example: app.example.com

openapi/components/schemas/sca/RecordSecurityEventRequest.yaml

@@ -0,0 +1,12 @@
+type: object
+description: >-
+  Records a client-side security-relevant event for the customer with the
+  underlying provider's risk engine (e.g. a sign-in, a sensitive view). Used to
+  feed the provider's adaptive-authentication signals.
+required:
+  - eventType
+properties:
+  eventType:
+    type: string
+    description: The provider-defined event type to record.
+    example: LOGIN

openapi/components/schemas/sca/ScaFactorList.yaml

@@ -0,0 +1,10 @@
+type: object
+description: The Strong Customer Authentication factors a customer has enrolled.
+required:
+  - factors
+properties:
+  factors:
+    type: array
+    description: The customer's enrolled SCA factors.
+    items:
+      $ref: ./ScaFactorView.yaml

openapi/components/schemas/sca/ScaFactorView.yaml

@@ -0,0 +1,21 @@
+type: object
+description: An enrolled Strong Customer Authentication factor.
+required:
+  - factor
+properties:
+  factor:
+    $ref: ./ScaFactor.yaml
+    description: The kind of enrolled factor.
+  credentialId:
+    type:
+      - string
+      - 'null'
+    description: >-
+      The per-credential id, populated only for `PASSKEY` factors (the id passed
+      to delete a passkey). Omitted for `TOTP` and `SMS_OTP`, which have no
+      per-credential id.
+  name:
+    type:
+      - string
+      - 'null'
+    description: An optional human-readable label for this factor.

openapi/components/schemas/sca/ScaLoginComplete.yaml

@@ -0,0 +1,13 @@
+type: object
+description: The provider-reported status of a completed SCA login session.
+required:
+  - status
+properties:
+  status:
+    type: string
+    description: >-
+      The provider-reported status of the login session, passed through
+      verbatim (Grid does not normalize it). A successful login reports
+      `SUCCESS`; other provider-specific values indicate the login did not
+      complete and should be surfaced to the caller.
+    example: SUCCESS

openapi/components/schemas/sca/ScaLoginCompleteRequest.yaml

@@ -0,0 +1,45 @@
+type: object
+description: >-
+  Completes an SCA login by submitting the proof for the started factor. Carries
+  the same proof fields as an `ScaAuthorization` (`code` for `SMS_OTP` / `TOTP`,
+  or `passkeyAssertion` + `origin` for `PASSKEY`), plus the `factor` being
+  completed and, for `SMS_OTP`, the `challengeId` returned by the login start.
+required:
+  - factor
+properties:
+  factor:
+    $ref: ./ScaFactor.yaml
+    description: The factor being completed; must match the started login.
+  challengeId:
+    type:
+      - string
+      - 'null'
+    description: >-
+      The challenge handle returned by the login start, required for `SMS_OTP`
+      and omitted for other factors.
+  code:
+    type:
+      - string
+      - 'null'
+    description: >-
+      The one-time code the customer received by SMS, or read from their
+      authenticator app. Provide for `SMS_OTP` / `TOTP`. In sandbox, the code is
+      always `123456`.
+    example: '123456'
+  passkeyAssertion:
+    type:
+      - object
+      - 'null'
+    additionalProperties: true
+    description: >-
+      Opaque WebAuthn assertion produced by the device from the login start's
+      `passkeyOptions`. Required when completing a `PASSKEY` login.
+  origin:
+    type:
+      - string
+      - 'null'
+    description: >-
+      The WebAuthn origin the `passkeyAssertion` was produced against (one of
+      the login start's `allowedOrigins`). Required alongside `passkeyAssertion`;
+      omit it for the `code` path.
+    example: https://app.example.com

openapi/components/schemas/sca/ScaLoginStart.yaml

@@ -0,0 +1,55 @@
+type: object
+description: >-
+  The factor-specific material a customer needs to complete an SCA login. Each
+  factor surfaces only the fields it issues: `SMS_OTP` carries `challengeId` and
+  `expiresAt`; `TOTP` carries neither (the customer reads the code from their
+  authenticator app); `PASSKEY` carries the opaque WebAuthn `passkeyOptions`
+  with `allowedOrigins` and `relyingPartyId`.
+required:
+  - factor
+properties:
+  factor:
+    $ref: ./ScaFactor.yaml
+    description: The factor this login was started for.
+  challengeId:
+    type:
+      - string
+      - 'null'
+    description: >-
+      The challenge handle for an `SMS_OTP` login, threaded back on the complete
+      call. Present only for `SMS_OTP`.
+  expiresAt:
+    type:
+      - string
+      - 'null'
+    format: date-time
+    description: >-
+      Absolute UTC timestamp after which the `SMS_OTP` code expires. Present
+      only for `SMS_OTP`.
+    example: '2025-10-03T12:05:00Z'
+  passkeyOptions:
+    type:
+      - object
+      - 'null'
+    additionalProperties: true
+    description: >-
+      Opaque WebAuthn assertion request options. Present only for `PASSKEY`;
+      pass to the device's WebAuthn API to produce the assertion submitted on
+      the complete call.
+  allowedOrigins:
+    type:
+      - array
+      - 'null'
+    items:
+      type: string
+    description: >-
+      The origins the WebAuthn ceremony may run against. Present only for
+      `PASSKEY`.
+    example:
+      - https://app.example.com
+  relyingPartyId:
+    type:
+      - string
+      - 'null'
+    description: The WebAuthn relying-party id. Present only for `PASSKEY`.
+    example: app.example.com

openapi/components/schemas/sca/ScaLoginStartRequest.yaml

@@ -0,0 +1,10 @@
+type: object
+description: >-
+  Selects which enrolled factor to start an SCA login with. The factor must
+  already be enrolled (or, for `SMS_OTP`, the phone verified).
+required:
+  - factor
+properties:
+  factor:
+    $ref: ./ScaFactor.yaml
+    description: The factor to authenticate with.

openapi/components/schemas/sca/TotpEnrollmentConfirmRequest.yaml

@@ -0,0 +1,20 @@
+type: object
+description: >-
+  The shared secret returned by the TOTP enrollment start, plus the first code
+  the customer's authenticator app produces, submitted to confirm and finalize
+  the TOTP factor.
+required:
+  - secret
+  - code
+properties:
+  secret:
+    type: string
+    description: >-
+      The shared secret returned as `secret` by the TOTP enrollment start,
+      threaded back to bind the confirmation to that enrollment.
+  code:
+    type: string
+    description: >-
+      The current time-based one-time code from the customer's authenticator
+      app. In sandbox, the code is always `123456`.
+    example: '123456'

openapi/components/schemas/sca/TotpEnrollmentConfirmResponse.yaml

@@ -0,0 +1,16 @@
+type: object
+description: >-
+  The one-time recovery codes issued once a TOTP factor is enrolled. These are
+  shown to the customer only once; store them somewhere safe to recover access
+  if the authenticator device is lost.
+required:
+  - recoveryCodes
+properties:
+  recoveryCodes:
+    type: array
+    description: The one-time recovery codes for this TOTP factor.
+    items:
+      type: string
+    example:
+      - ABCD-EFGH-IJKL
+      - MNOP-QRST-UVWX

openapi/components/schemas/sca/TotpEnrollmentStart.yaml

@@ -0,0 +1,25 @@
+type: object
+description: >-
+  The shared secret a customer's authenticator app needs to enroll a TOTP
+  factor. Returned by `POST /customers/{customerId}/sca/factors/totp`; the
+  customer scans `totpUri` (an `otpauth://` provisioning URI) and confirms with
+  the first code their app produces.
+required:
+  - secret
+  - secretBase32Encoded
+  - totpUri
+properties:
+  secret:
+    type: string
+    description: The raw TOTP shared secret.
+  secretBase32Encoded:
+    type: string
+    description: >-
+      The Base32-encoded shared secret, suitable for manual entry into an
+      authenticator app that does not scan QR codes.
+  totpUri:
+    type: string
+    description: >-
+      The `otpauth://` provisioning URI (the QR-code payload) the customer's
+      authenticator app scans to enroll the factor.
+    example: otpauth://totp/Grid:customer@example.com?secret=ABC123&issuer=Grid