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

[jklein24]

Summary

The SCA management surface for EU (Striga) customers — the customer-level setup, session, and recovery flows that sit alongside per-payment authorization (not inside it). This single PR collapses the original design's PR3–PR7 (enrollment, passkey, login/session, beneficiary trust, 2FA reset). Stacks on #558, which defines the per-transaction authorization core and the shared schemas this PR reuses. All endpoints are EU-only — 409 for providers that don't require SCA (the invisibility guarantee) and mirror the sparkcore handlers' exact routes + JSON shapes. Surfaced after an audit of #558 found these existed only as sparkcore temp types, not in the spec.

Covered by this PR

• Factor enrollment (design PR3/PR4): POST /customers/{id}/sca/factors/totp (+/confirm), .../passkey (+/confirm), GET .../sca/factors, DELETE .../passkey/{credentialId}.
• Login / 180-day session (PR5): POST .../sca/login/start (+/complete); POST .../sca/record-event.
• Beneficiary trust (PR6): POST .../external-accounts/{extId}/trust (issues the challenge + whitelistedId), .../trust/confirm, .../untrust/confirm — the whitelisting exemption that lets recurring payees skip per-transaction SCA.
• 2FA reset / recovery (PR7): POST .../sca/factors/reset (201) → GET .../reset/{resetId} (poll to LIVENESS_PASSED) → POST .../reset/{resetId}/complete.

Reuses ScaFactor / ScaChallenge / ScaAuthorization from #558; confirm/login bodies carry the code | passkeyAssertion + origin proof, and beneficiary confirm threads whitelistedId back so confirm never re-whitelists (no duplicate SMS). TwoFactorResetStatus / ScaLoginComplete document their provider-passthrough terminal values (LIVENESS_PASSED / SUCCESS).

NOT in this PR

• Per-transaction authorization — the challenge on a debit, the authorize / resend endpoints, and inline scaAuthorization / scaFactor — that's feat(sca): add Strong Customer Authentication surface #558.
• The sparkcore backend for these endpoints (separate stack), and client-side WebAuthn ceremony logic (Grid relays opaque passkey blobs; it performs no crypto).

Known gaps / follow-ups (tracked in the design doc addendum)

• Untrust has confirm but no start, and there is no trust-list read — a caller who loses whitelistedId (or needs the untrust OTP re-sent) is stuck (addendum F4). The trusted-beneficiary exemption benefit (a trusted payee actually skipping per-tx SCA) is also not yet realized in the backend.
• Reset status documents LIVENESS_PASSED / PENDING but no terminal failure value — infinite-poll risk (F10).
• Distinct SCA 409 codes (SCA_NOT_REQUIRED vs NO_PENDING_SCA_CHALLENGE) are not yet modeled (F9).

Validation

npm run lint:openapi (redocly + spectral, fail-on-error) passes clean; additions are additive / non-breaking. (The OpenAPI build / breaking-changes / lint CI checks run on the base=main PR #558; they do not run here because this PR targets feat/striga-sca.)

Notes

• Field shapes mirror the sparkcore implementation (the source of truth until the SDK regenerates). A few Striga response bodies (login-complete, reset-status/complete, passkey list/delete) are typed from the sparkcore to_dict() since Striga's docs only cover the start side — flagged for sandbox verification.

Stacking

main → #558 (per-transaction) → #600 (this PR). Merges after #558; depends on the schemas #558 introduces.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	Jul 17, 2026 6:07pm
grid-wallet-demo	Ignored	Preview	Jul 17, 2026 6:07pm

[github-actions]

✱ Stainless preview builds for grid

This PR will update the grid SDKs with the following commit messages.

cli

chore(internal): regenerate SDK with no functional changes

go

chore(internal): regenerate SDK with no functional changes

kotlin

chore(internal): regenerate SDK with no functional changes

openapi

feat(api): add SCA factor management, login, 2FA reset, beneficiary trust endpoints

php

chore(internal): regenerate SDK with no functional changes

python

chore(internal): regenerate SDK with no functional changes

ruby

chore(internal): regenerate SDK with no functional changes

typescript

chore(internal): regenerate SDK with no functional changes

⚠️grid-openapistudio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️

✅ grid-rubystudio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

⚠️grid-gostudio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ❗

go get github.com/stainless-sdks/grid-go@1fe4485bac5384b80a875cf3663b8897ecde9a45

⚠️grid-kotlinstudio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ⚠️ → build ✅ → lint ✅ → test ❗

⚠️grid-pythonstudio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ❗

pip install https://pkg.stainless.com/s/grid-python/b17c66ee377f16f682424d9b3fa060201e16c7b4/grid-0.0.1-py3-none-any.whl

✅ grid-typescriptstudio · conflict

Your SDK build had at least one note diagnostic.

✅ grid-phpstudio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → lint ✅ → test ✅

⚠️grid-clistudio · code

Your SDK build had a failure in the build CI job, which is a regression from the base state.
generate ⚠️ → build ❗ → lint ❗ → test ❗

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-07-17 23:15:33 UTC

[jklein24]

@greptile review

[greptile-apps]

Greptile Summary

\m/ ⚡ RIFF OF THE SPEC DESCENDS ⚡ \m/
|===========================================|
| S C A M A N A G E M E N T |
| ~~ THRASH THE ENROLLMENT FLOWS ~~ |
|===========================================|
\m/ \m/

This PR adds the EU SCA management surface — factor enrollment (TOTP + passkey), the 180-day login/session flow, beneficiary trust/untrust, and 2FA liveness-gated reset — as 13 new OpenAPI paths and 22 new schemas, completing design PR3–PR7 that stacked on the per-transaction core in #558.

• Factor enrollment & management:POST .../sca/factors/totp (+/confirm), .../passkey (+/confirm), GET .../sca/factors, DELETE .../passkey/{credentialId} — all returning 409 for non-SCA regions and mirroring sparkcore route shapes.
• Login, security events, and 2FA reset:POST .../sca/login/start (+/complete), POST .../sca/record-event, and the POST .../sca/factors/reset → poll → /complete liveness flow with documented LIVENESS_PASSED sentinel after prior review iteration.
• Beneficiary trust/untrust:POST .../trust → POST .../trust/confirm and POST .../untrust/confirm with a shared BeneficiaryTrustConfirmRequest; the whitelistedId field the PR description says is issued by the start and threaded on confirm is absent from both schemas, and anyOf in the confirm request (and ScaLoginCompleteRequest) should be oneOf to enforce mutual exclusion between OTP and passkey proof types.

Confidence Score: 4/5

Mergeable after resolving two spec gaps: the missing whitelistedId field in the trust start/confirm schemas and the anyOf-vs-oneOf discriminator ambiguity.

The trust-start response schema omits the whitelistedId the PR description says is issued and threaded back on confirm — if the sparkcore backend requires it, every trust-confirm call will fail silently. Separately, anyOf in both confirm-request schemas permits a caller to submit both an OTP code and a passkey assertion simultaneously, leaving the server to receive an ambiguous proof payload with no spec guidance on which to use.

BeneficiaryTrustStart.yaml, BeneficiaryTrustConfirmRequest.yaml, and ScaLoginCompleteRequest.yaml need attention before merge.

Important Files Changed

Filename	Overview
openapi/components/schemas/sca/BeneficiaryTrustStart.yaml	Trust-start response schema is missing the whitelistedId field the PR description says it returns; the confirm request is also missing it as an input.
openapi/components/schemas/sca/ScaLoginCompleteRequest.yaml	Uses anyOf instead of oneOf for the OTP/passkey proof discriminator, allowing both proof types to be submitted in the same request; same issue in BeneficiaryTrustConfirmRequest.
openapi/components/schemas/sca/BeneficiaryTrustConfirmRequest.yaml	Same anyOf-vs-oneOf issue as ScaLoginCompleteRequest; also missing whitelistedId that the PR description says must be threaded back on confirm.
openapi/paths/customers/customers_{customerId}_sca_factors_reset.yaml	2FA reset start endpoint correctly returns 201 and threads resetId through to status/complete; no issues found.
openapi/paths/customers/customers_{customerId}external-accounts{externalAccountId}_trust.yaml	Trust-start endpoint has no request body (correctly inferred from path) but returns a BeneficiaryTrustStart that omits the whitelistedId the PR description says is issued here.
openapi/paths/customers/customers_{customerId}external-accounts{externalAccountId}_trust_confirm.yaml	Trust-confirm endpoint structure is clean; underlying BeneficiaryTrustConfirmRequest schema has the anyOf/whitelistedId issues flagged separately.
openapi/openapi.yaml	All 13 new path refs wired correctly; ordering and grouping is consistent with existing paths.
.redocly.lint-ignore.yaml	Suppressions added for anyOf branches referencing parent-level properties; comment explains the valid JSON Schema rationale.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant C as Caller
participant G as Grid API
participant S as Striga (SCA Provider)
Note over C,S: Factor Enrollment — TOTP
C->>G: "POST /customers/{id}/sca/factors/totp"
G->>S: start TOTP enrollment
S-->>G: secret + totpUri
G-->>C: "TotpEnrollmentStart {secret, secretBase32Encoded, totpUri}"
C->>G: "POST /sca/factors/totp/confirm {secret, code}"
G->>S: confirm TOTP
S-->>G: recovery codes
G-->>C: "TotpEnrollmentConfirmResponse {recoveryCodes}"
Note over C,S: SCA Login — SMS_OTP
C->>G: "POST /customers/{id}/sca/login/start {factor: SMS_OTP}"
G->>S: dispatch OTP
S-->>G: challengeId + expiresAt
G-->>C: "ScaLoginStart {factor, challengeId, expiresAt}"
C->>G: "POST /sca/login/complete {factor, challengeId, code}"
G->>S: verify code
S-->>G: status
G-->>C: "ScaLoginComplete {status: SUCCESS}"
Note over C,S: Beneficiary Trust
C->>G: "POST /customers/{id}/external-accounts/{extId}/trust"
G->>S: start trust
S-->>G: scaChallenge (optional)
G-->>C: "BeneficiaryTrustStart {scaChallenge?}"
C->>G: "POST .../trust/confirm {challengeId?, code|passkeyAssertion+origin}"
G->>S: confirm trust
S-->>G: "trusted=true"
G-->>C: "BeneficiaryTrustConfirm {trusted: true}"
Note over C,S: 2FA Reset
C->>G: "POST /customers/{id}/sca/factors/reset {factor}"
G->>S: start liveness
S-->>G: resetId + liveness handles
G-->>C: "TwoFactorResetStart {resetId, livenessAccessToken?, verificationLink?}"
loop Poll until LIVENESS_PASSED
C->>G: "GET /sca/factors/reset/{resetId}"
G->>S: check status
S-->>G: status
G-->>C: "TwoFactorResetStatus {status}"
end
C->>G: "POST /sca/factors/reset/{resetId}/complete"
G->>S: complete reset
G-->>C: 204 No Content

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant C as Caller
participant G as Grid API
participant S as Striga (SCA Provider)
Note over C,S: Factor Enrollment — TOTP
C->>G: "POST /customers/{id}/sca/factors/totp"
G->>S: start TOTP enrollment
S-->>G: secret + totpUri
G-->>C: "TotpEnrollmentStart {secret, secretBase32Encoded, totpUri}"
C->>G: "POST /sca/factors/totp/confirm {secret, code}"
G->>S: confirm TOTP
S-->>G: recovery codes
G-->>C: "TotpEnrollmentConfirmResponse {recoveryCodes}"
Note over C,S: SCA Login — SMS_OTP
C->>G: "POST /customers/{id}/sca/login/start {factor: SMS_OTP}"
G->>S: dispatch OTP
S-->>G: challengeId + expiresAt
G-->>C: "ScaLoginStart {factor, challengeId, expiresAt}"
C->>G: "POST /sca/login/complete {factor, challengeId, code}"
G->>S: verify code
S-->>G: status
G-->>C: "ScaLoginComplete {status: SUCCESS}"
Note over C,S: Beneficiary Trust
C->>G: "POST /customers/{id}/external-accounts/{extId}/trust"
G->>S: start trust
S-->>G: scaChallenge (optional)
G-->>C: "BeneficiaryTrustStart {scaChallenge?}"
C->>G: "POST .../trust/confirm {challengeId?, code|passkeyAssertion+origin}"
G->>S: confirm trust
S-->>G: "trusted=true"
G-->>C: "BeneficiaryTrustConfirm {trusted: true}"
Note over C,S: 2FA Reset
C->>G: "POST /customers/{id}/sca/factors/reset {factor}"
G->>S: start liveness
S-->>G: resetId + liveness handles
G-->>C: "TwoFactorResetStart {resetId, livenessAccessToken?, verificationLink?}"
loop Poll until LIVENESS_PASSED
C->>G: "GET /sca/factors/reset/{resetId}"
G->>S: check status
S-->>G: status
G-->>C: "TwoFactorResetStatus {status}"
end
C->>G: "POST /sca/factors/reset/{resetId}/complete"
G->>S: complete reset
G-->>C: 204 No Content

Loading

_{Reviews (7): Last reviewed commit: "docs(sca): enumerate record-event values..." | Re-trigger Greptile}

[jklein24]

@greptile review

[jklein24]

@greptile review

[jklein24]

• docs(sca): document Strong Customer Authentication for EU customers #683
• feat(sca): SCA management surface — enrollment, login/session, beneficiary trust, 2FA reset #600 👈 (View in Graphite)
• feat(sca): add Strong Customer Authentication surface #558
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[jklein24]

@faraday review this

[ls-bolt]

📌 Bolt Status

2026-07-09 06:52:06 UTC — ⚡ Agent bright-palladium(#1) started

---

Feedback

[pengying]

do we need explicit nulls here? I saw this in another PR but always thought that the field would be excluded vs explicitly null'd out

[jklein24]

Yeah, good call — dropped them. These are genuinely omitted for TOTP/SMS_OTP, not sent as null, so plain-optional is the right contract and the explicit null was just wrong here.

fwiw the rule I'm going by: nullable and optional are separate axes. Leave a field out of required when the key can be absent; only add 'null' to the type when the server actually puts "field": null on the wire. A few of the newer sca/agents schemas started reaching for explicit null where the field is really just omitted — that's the inconsistency you're seeing. Fixing those as I hit them.

[pengying]

wait who dis?

[pengying]

LGTM 2 general questions
1. how does someone add sms otp
2. do we need -null as a type if the field is optional or are we explicitly setting it to null.

[pengying]

Is enrolling the concept of trusting a user device / auth method. What triggers the sms otp?

[jklein24]

Yes, it is. With striga, sms is enrolled by default since creating a customer requires sms and email verification via the contact verification API flows. I could definitely document this a bit better here, though. Striga does that at the top of this page: https://docs.striga.com/reference/enrollment. I'll clarify the SMS_OTP line here to indicate that all customers need a verified phone at customer creation in SCA-regulated regions. See the "verifications" routes.

[pengying]

so then when the customer is created, they provide the phone number as part of customer creation. we auto send a sms otp?

What if they change phone numbers? is that a patch to customer.phone_number that triggers a sms otp? or do we make it explicit here?

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	Jul 17, 2026, 6:04 PM

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Grid	🟡 Building	–	Jul 17, 2026, 6:03 PM