[grid] fix Global Account auth snippets

[DhruvPareek]

Summary

• Fix the Global Account auth summary so EMAIL_OTP describes the encrypted OTP + signed retry flow instead of the old one-shot verify flow.
• Split OAUTH into its own summary bullet because it remains the one-shot verify flow with clientPublicKey.
• Make Android and iOS passkey snippets explicit that the returned hex challenge string must be UTF-8 encoded as WebAuthn challenge bytes.

Validation

• make build at the stack tip

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	Jun 10, 2026 6:34pm

[DhruvPareek]

• [grid] fix Global Account sandbox docs #567
• [grid] fix Global Account auth snippets #566 👈 (View in Graphite)
• [grid] fix passkey registration samples #565
• [grid] fix Global Account HPKE docs #564
• [grid] fix Global Account frontend auth sample #563
• [grid] clarify email OTP registration bundle docs #562
• [grid] fix passkey reauth challenge docs #561
• main

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

[greptile-apps]

Greptile Summary

This documentation-only PR updates the Global Account authentication reference in authentication.mdx with two focused fixes: it rewrites the EMAIL_OTP summary bullet to accurately describe the HPKE-encrypted OTP plus signed-retry flow, and clarifies in the Android and iOS passkey code snippets that the Grid-issued hex challenge must be UTF-8-encoded before being passed to the platform WebAuthn APIs.

• EMAIL_OTP/OAUTH split: The combined bullet is replaced by two separate bullets — EMAIL_OTP now describes the full challenge → HPKE-encrypt → verify → 202 → signed-retry sequence, while OAUTH retains the simpler one-shot verify with clientPublicKey.
• Android snippet: Adds val webAuthnChallenge = base64UrlEncode(challengeResp.challenge.toByteArray(Charsets.UTF_8)) and passes the result to buildWebAuthnGetOptionsJson, matching what GetPublicKeyCredentialOption expects (base64url in the JSON options string).
• iOS snippet: Changes the assertion request to challenge: Data(challengeResp.challenge.utf8), correctly UTF-8-encoding the hex string into Data bytes for ASAuthorizationPlatformPublicKeyCredentialProvider.

Confidence Score: 5/5

Documentation-only change with no runtime code; all updated descriptions and snippets are consistent with each other and with the detailed sections in the same file.

The PR touches only an MDX documentation file. The rewritten EMAIL_OTP and OAUTH bullets match the existing detailed flow diagrams and curl examples further down the page. The Android and iOS platform encoding changes are correct: Android base64url-encodes the UTF-8 bytes for the JSON options string consumed by GetPublicKeyCredentialOption, and iOS uses Data(string.utf8) which is the standard Swift pattern for getting raw UTF-8 bytes.

No files require special attention.

Important Files Changed

Filename	Overview
mintlify/snippets/global-accounts/authentication.mdx	Documentation-only update: splits EMAIL_OTP/OAUTH summary bullets and adds explicit UTF-8 encoding steps to Android and iOS passkey snippets; changes are logically consistent with the detailed sections below.

Sequence Diagram

sequenceDiagram
  participant C as Client
  participant IB as Integrator backend
  participant G as Grid
  participant E as Email / OIDC

  note over C,G: EMAIL_OTP (updated flow)
  C->>IB: POST /my-backend/otp/challenge
  IB->>G: "POST /auth/credentials/{id}/challenge"
  G->>E: deliver OTP email
  G-->>IB: "200 { otpEncryptionTargetBundle }"
  IB-->>C: "{ otpEncryptionTargetBundle }"
  C->>C: generateClientKeyPair() (P-256 TEK)
  C->>C: "HPKE-encrypt { otp_code, publicKey } to encryptedOtpBundle"
  IB->>G: "POST /auth/credentials/{id}/verify { type: EMAIL_OTP, encryptedOtpBundle }"
  G-->>IB: "202 { payloadToSign, requestId }"
  C->>C: sign(payloadToSign, tekPrivateKey)
  IB->>G: Same POST + Grid-Wallet-Signature + Request-Id
  G-->>IB: 200 AuthSession (no encryptedSessionSigningKey)

  note over C,G: OAUTH (one-shot flow)
  C->>E: fresh OIDC token
  E-->>C: id_token
  IB->>G: "POST /auth/credentials/{id}/verify { type: OAUTH, oidcToken, clientPublicKey }"
  G-->>IB: "200 AuthSession { encryptedSessionSigningKey }"

Loading

_{Reviews (4): Last reviewed commit: "[grid] fix Global Account auth snippets" | Re-trigger Greptile}

[restamp-bot]

7da0598 is a pure rebase onto c14ff52. Approving based on @carsonp6's previous approval of 2e284b5.

[restamp-bot]

460893f is a pure rebase onto 2bf47ea. Approving based on @carsonp6's previous approval of 2e284b5.

[restamp-bot]

460893f is a pure rebase onto 2bf47ea. Approving based on @carsonp6's previous approval of 2e284b5.

[restamp-bot]

d409949 is a pure rebase onto 43b4727. Approving based on @carsonp6's previous approval of 2e284b5.

[restamp-bot]

d409949 is a pure rebase onto 43b4727. Approving based on @carsonp6's previous approval of 2e284b5.

The base branch was changed.

[restamp-bot]

d409949 is a pure rebase onto 43b4727. Approving based on @carsonp6's previous approval of 2e284b5.

[restamp-bot]

f856ba9 is a pure rebase onto 43b4727. Approving based on @carsonp6's previous approval of 2e284b5.

[DhruvPareek]

Merge activity

• Jun 10, 6:36 PM UTC: @DhruvPareek merged this pull request with Graphite.