[grid] clarify email OTP registration bundle docs

[DhruvPareek]

Clarifies the Global Accounts EMAIL_OTP docs source to match backend behavior. Registration may include otpEncryptionTargetBundle when adding EMAIL_OTP back through the signed-retry flow, but first-time EMAIL_OTP wallet bootstrap can omit it. Clients should call POST /auth/credentials/{id}/challenge when the bundle is absent before building encryptedOtpBundle.

[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 9, 2026 7:55pm

[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

csharp

docs(api): clarify otpEncryptionTargetBundle behavior in EMAIL_OTP flow

go

docs(api): clarify otpEncryptionTargetBundle availability in EMAIL_OTP flow

kotlin

docs(api): clarify otpEncryptionTargetBundle optionality in EMAIL_OTP credential flow

openapi

docs(api): clarify otpEncryptionTargetBundle presence in EMAIL_OTP auth flows

php

docs(api): clarify otpEncryptionTargetBundle behavior in EMAIL_OTP auth flow

python

docs(api): update EMAIL_OTP verification flow descriptions in auth/credentials

ruby

docs(api): clarify otp_encryption_target_bundle optionality in auth credential responses

typescript

docs(api): clarify otpEncryptionTargetBundle behavior in auth credentials EMAIL_OTP flow

✅ grid-openapi studio · code

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

✅ grid-ruby studio · code

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

⚠️ grid-go studio · 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@28d68ec0639f157c605b8436ee2960919096ba20

✅ grid-kotlin studio · code

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

⚠️ grid-python studio · 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/e7545b44da28c74214dab7e40435cde38e61490b/grid-0.0.1-py3-none-any.whl

⚠️ grid-csharp studio · code

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

✅ grid-php studio · code

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

✅ grid-typescript studio · code

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

npm install https://pkg.stainless.com/s/grid-typescript/0695f3c3f7ba16e5d0e6fb982eec07e7731178d9/dist.tar.gz

⚠️ grid-cli studio · code

Your SDK build had a failure in the test 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-06-10 17:14:06 UTC

[DhruvPareek]

• [grid] fix Global Account sandbox docs #567
• [grid] fix Global Account auth snippets #566
• [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 👈 (View in Graphite)
• [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 PR clarifies the EMAIL_OTP registration documentation to accurately reflect that otpEncryptionTargetBundle is not always present in POST /auth/credentials responses — it is included when adding EMAIL_OTP back through the signed-retry flow, but may be omitted on first-time wallet bootstrap, in which case clients must call POST /auth/credentials/{id}/challenge to obtain it before verifying.

• All source files updated: openapi/paths/auth/auth_credentials.yaml, auth_credentials_{id}_verify.yaml, AuthMethodResponse.yaml, and EmailOtpCredentialVerifyRequestFields.yaml are all updated alongside the generated openapi.yaml and mintlify/openapi.yaml, addressing the concern raised in the previous review thread.
• MDX guides updated: authentication.mdx and client-keys.mdx both add clear guidance to call /challenge when the bundle is absent from the registration response.
• One inconsistency to resolve: auth_credentials.yaml says the signed-retry response unconditionally "carries" the bundle, while authentication.mdx adds "when present, or call challenge if absent" — these need to be aligned on whether the bundle is guaranteed or conditional in the signed-retry path.

Confidence Score: 4/5

Documentation-only change; safe to merge after resolving the inconsistency between the API spec and the MDX walkthrough on whether the bundle is guaranteed in the signed-retry path.

The API spec (auth_credentials.yaml) unconditionally states the signed-retry response carries otpEncryptionTargetBundle, while the MDX add-credential walkthrough says when present, or call /challenge if absent — a developer following one source will write different client logic than one following the other.

mintlify/snippets/global-accounts/authentication.mdx — the add-credential activation step needs its when present wording reconciled with the unconditional language in openapi/paths/auth/auth_credentials.yaml.

Important Files Changed

Filename	Overview
openapi/paths/auth/auth_credentials.yaml	201 description updated to distinguish signed-retry (bundle always present) from first-time bootstrap (bundle may be absent); source change will survive make build.
openapi/paths/auth/auth_credentials_{id}_verify.yaml	EMAIL_OTP verify description updated to say from registration when present, or from /challenge when registration omitted it; language is consistent with the other source files.
openapi/components/schemas/auth/AuthMethodResponse.yaml	Schema description and otpEncryptionTargetBundle property description updated to reflect conditional bundle presence; wording is clear and internally consistent.
openapi/components/schemas/auth/EmailOtpCredentialVerifyRequestFields.yaml	Verify-request description updated to state from registration when present, or from /challenge when omitted; consistent with peer schema files.
mintlify/snippets/global-accounts/authentication.mdx	Add-credential step updated with defensive when present / if absent wording that conflicts with auth_credentials.yaml which unconditionally states the bundle is present in the signed-retry flow.
mintlify/snippets/global-accounts/client-keys.mdx	Bundle-source explanation and inline comment updated to reflect first-time bootstrap may omit the bundle; clear and actionable guidance added.
openapi.yaml	Generated file updated identically to the source files; changes will be preserved as long as make build is run from the updated source.
mintlify/openapi.yaml	Generated Mintlify copy updated to mirror the main openapi.yaml changes; matches source changes exactly.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[POST /auth/credentials] --> B{Which flow?}
    B -->|First-time EMAIL_OTP bootstrap| C[201 AuthMethod response]
    B -->|Add EMAIL_OTP via signed-retry| D[201 AuthMethod + otpEncryptionTargetBundle]
    C --> E{otpEncryptionTargetBundle present?}
    E -->|Yes| F[HPKE-encrypt OTP with bundle]
    E -->|No| G[POST /auth/credentials/id/challenge]
    G --> H[Receive otpEncryptionTargetBundle]
    H --> F
    D --> F
    F --> I[POST /auth/credentials/id/verify with encryptedOtpBundle]
    I --> J[202 payloadToSign + verificationToken]
    J --> K[Sign verificationToken with TEK private key]
    K --> L[Retry POST /auth/credentials/id/verify with Grid-Wallet-Signature]
    L --> M[200 AuthSession issued]

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
mintlify/snippets/global-accounts/authentication.mdx:718
**Inconsistency between add-credential docs and the API spec description**

The updated step says `EMAIL_OTP` uses the `otpEncryptionTargetBundle` "from the signed-retry registration response **when present**, or first calls `POST /auth/credentials/{id}/challenge` if the bundle is absent." However, `openapi/paths/auth/auth_credentials.yaml` (also updated in this PR) says the signed-retry response unconditionally "also carries `otpEncryptionTargetBundle`" — making the bundle always present in that flow. A developer reading the MDX add-credential walkthrough would conclude the bundle is optional in the signed-retry case and defensively add a challenge call, while the API spec implies it is always delivered. If the backend truly can omit the bundle even on the signed-retry path, the spec language should be softened to "may carry"; if it is always present there, the MDX should say "use the bundle from the signed-retry response" without the "when present / if absent" hedge.

_{Reviews (3): Last reviewed commit: "[grid] clarify email OTP registration bu..." | Re-trigger Greptile}

[pengying]

Valid comment about the edit to the merged openapi file instead of the source files

[pengying]

update the source openapi files vs the merged one

[pengying]

probably need to regenerate the openapi after the schema changes

[DhruvPareek]

already regenerated w 'make build' and it profuced no diff

[DhruvPareek]

so openapi.yaml and mintlify/openapi.yaml are up to date

[DhruvPareek]

Merge activity

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