docs: add sandbox email OTP inbox endpoint#489
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Warning This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
This stack of pull requests is managed by Graphite. Learn more about stacking. |
✱ Stainless preview builds for gridThis PR will update the cli csharp go kotlin openapi php python ruby typescript Edit this comment to update them. They will appear in their respective SDK's changelogs. ✅ grid-openapi studio · code · diff
🚧 grid-ruby studio
✅ grid-go studio · code · diff
✅ grid-typescript studio · code · diff
✅ grid-kotlin studio · code · diff
✅ grid-python studio · code · diff
✅ grid-csharp studio · code · diff
✅ grid-php studio · code · diff
✅ grid-cli studio · code · diff
This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push. |
DhruvPareek
changed the base branch from
dp/docs-sandbox-oidc-token
to
graphite-base/489
DhruvPareek
force-pushed
the
graphite-base/489
branch
from
8ad3d9a to
907c2cd
Compare
DhruvPareek
force-pushed
the
dp/docs-sandbox-email-otp
branch
from
1971b3b to
6b3905e
Compare
Greptile SummaryThis PR documents the new
Confidence Score: 4/5Safe to merge; changes are documentation and spec-only with no application logic. The endpoint definition, schema, and prose are well-structured. Two minor documentation inconsistencies were found: the openapi/components/schemas/sandbox/SandboxEmailOtpResponse.yaml and mintlify/snippets/sandbox-global-account-magic.mdx are worth a quick look before merging.
|
| Filename | Overview |
|---|---|
| openapi/paths/sandbox/sandbox_email-otps_latest.yaml | New GET endpoint definition for sandbox OTP inbox; error responses and required parameter are correctly specified. |
| openapi/components/schemas/sandbox/SandboxEmailOtpResponse.yaml | New schema for sandbox OTP response; the email field's description ('Email address or display name') conflicts with its format: email constraint. |
| mintlify/snippets/sandbox-global-account-magic.mdx | Email OTP section rewritten to use sandbox inbox; new bash example uses $GRID_BASE_URL variable while all other examples in the same file use hardcoded URLs. |
| mintlify/global-accounts/platform-tools/sandbox-testing.mdx | Description and 'Moving to production' step updated to reflect sandbox inbox instead of magic OTP value; changes are accurate and consistent. |
| openapi/openapi.yaml | Root spec correctly wires up the new path reference alongside the existing sandbox webhook path. |
| openapi.yaml | Generated bundle updated with new endpoint and schema; Error403 definition relocated (no content change). |
| mintlify/openapi.yaml | Mintlify copy of generated bundle updated in sync with root openapi.yaml; changes mirror the source spec. |
| mintlify/global-accounts/index.mdx | Card description for the sandbox-testing page updated to reflect inbox-based OTP; no issues. |
Sequence Diagram
sequenceDiagram
participant Client
participant GridSandbox as Grid Sandbox API
Note over Client,GridSandbox: 1. Register EMAIL_OTP credential
Client->>GridSandbox: POST /auth/credentials (type: EMAIL_OTP)
GridSandbox-->>Client: 201 Created - authMethodId returned
Note over Client,GridSandbox: 2. Retrieve OTP from sandbox inbox (new endpoint)
Client->>GridSandbox: GET /sandbox/email-otps/latest with authMethodId query param
GridSandbox-->>Client: 200 SandboxEmailOtpResponse with otpCode
Note over Client,GridSandbox: 3. Verify with live OTP code
Client->>GridSandbox: "POST /auth/credentials/{id}/verify with otpCode"
GridSandbox-->>Client: 200 Session and encrypted session signing key
Prompt To Fix All With AI
Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 2
openapi/components/schemas/sandbox/SandboxEmailOtpResponse.yaml:19-23
The `email` field description says "Email address or display name" but the field declares `format: email`, which expects a plain RFC 5321 address. A display name like `Alice Smith <alice@example.com>` would fail `format: email` validation in strict validators. Either drop "or display name" from the description (if the field is always a bare email address) or remove `format: email` (if the field can hold display-name notation).
```suggestion
email:
type: string
format: email
description: Email address associated with the auth method.
example: alice@example.com
```
### Issue 2 of 2
mintlify/snippets/sandbox-global-account-magic.mdx:12-15
The Email OTP example references `$GRID_BASE_URL`, but every other example in this snippet — passkey, wallet signature, OAuth — uses the fully-qualified hardcoded URL (`https://api.lightspark.com/grid/2025-10-13/...`). `$GRID_BASE_URL` is never defined on the page, so a reader who copies only this block will get a broken curl command. For consistency with the rest of the snippet, use the same hardcoded base URL.
```suggestion
OTP_CODE=$(curl -sS "https://api.lightspark.com/grid/2025-10-13/sandbox/email-otps/latest?authMethodId=AuthMethod:abc123" \
-u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" | jq -r '.otpCode')
curl -X POST "https://api.lightspark.com/grid/2025-10-13/auth/credentials/AuthMethod:abc123/verify" \
```
Reviews (1): Last reviewed commit: "docs: add sandbox email OTP inbox endpoi..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| email: | ||
| type: string | ||
| format: email | ||
| description: Email address or display name associated with the auth method. | ||
| example: alice@example.com |
There was a problem hiding this comment.
email field description says "Email address or display name" but the field declares format: email, which expects a plain RFC 5321 address. A display name like Alice Smith <alice@example.com> would fail format: email validation in strict validators. Either drop "or display name" from the description (if the field is always a bare email address) or remove format: email (if the field can hold display-name notation).
| email: | |
| type: string | |
| format: email | |
| description: Email address or display name associated with the auth method. | |
| example: alice@example.com | |
| email: | |
| type: string | |
| format: email | |
| description: Email address associated with the auth method. | |
| example: alice@example.com |
Prompt To Fix With AI
This is a comment left during a code review.
Path: openapi/components/schemas/sandbox/SandboxEmailOtpResponse.yaml
Line: 19-23
Comment:
The `email` field description says "Email address or display name" but the field declares `format: email`, which expects a plain RFC 5321 address. A display name like `Alice Smith <alice@example.com>` would fail `format: email` validation in strict validators. Either drop "or display name" from the description (if the field is always a bare email address) or remove `format: email` (if the field can hold display-name notation).
```suggestion
email:
type: string
format: email
description: Email address associated with the auth method.
example: alice@example.com
```
How can I resolve this? If you propose a fix, please make it concise.
| OTP_CODE=$(curl -sS "$GRID_BASE_URL/sandbox/email-otps/latest?authMethodId=AuthMethod:abc123" \ | ||
| -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" | jq -r '.otpCode') | ||
|
|
||
| curl -X POST "$GRID_BASE_URL/auth/credentials/AuthMethod:abc123/verify" \ |
There was a problem hiding this comment.
$GRID_BASE_URL, but every other example in this snippet — passkey, wallet signature, OAuth — uses the fully-qualified hardcoded URL (https://api.lightspark.com/grid/2025-10-13/...). $GRID_BASE_URL is never defined on the page, so a reader who copies only this block will get a broken curl command. For consistency with the rest of the snippet, use the same hardcoded base URL.
| OTP_CODE=$(curl -sS "$GRID_BASE_URL/sandbox/email-otps/latest?authMethodId=AuthMethod:abc123" \ | |
| -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" | jq -r '.otpCode') | |
| curl -X POST "$GRID_BASE_URL/auth/credentials/AuthMethod:abc123/verify" \ | |
| OTP_CODE=$(curl -sS "https://api.lightspark.com/grid/2025-10-13/sandbox/email-otps/latest?authMethodId=AuthMethod:abc123" \ | |
| -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" | jq -r '.otpCode') | |
| curl -X POST "https://api.lightspark.com/grid/2025-10-13/auth/credentials/AuthMethod:abc123/verify" \ |
Prompt To Fix With AI
This is a comment left during a code review.
Path: mintlify/snippets/sandbox-global-account-magic.mdx
Line: 12-15
Comment:
The Email OTP example references `$GRID_BASE_URL`, but every other example in this snippet — passkey, wallet signature, OAuth — uses the fully-qualified hardcoded URL (`https://api.lightspark.com/grid/2025-10-13/...`). `$GRID_BASE_URL` is never defined on the page, so a reader who copies only this block will get a broken curl command. For consistency with the rest of the snippet, use the same hardcoded base URL.
```suggestion
OTP_CODE=$(curl -sS "https://api.lightspark.com/grid/2025-10-13/sandbox/email-otps/latest?authMethodId=AuthMethod:abc123" \
-u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" | jq -r '.otpCode')
curl -X POST "https://api.lightspark.com/grid/2025-10-13/auth/credentials/AuthMethod:abc123/verify" \
```
How can I resolve this? If you propose a fix, please make it concise.
DhruvPareek
force-pushed
the
dp/docs-sandbox-email-otp
branch
from
6b3905e to
db2d144
Compare
DhruvPareek
force-pushed
the
graphite-base/489
branch
from
907c2cd to
8983815
Compare
DhruvPareek
changed the base branch from
graphite-base/489
to
dp/docs-realistic-oidc-sandbox
DhruvPareek
force-pushed
the
dp/docs-sandbox-email-otp
branch
from
db2d144 to
594dbdf
Compare
DhruvPareek
force-pushed
the
dp/docs-sandbox-email-otp
branch
from
594dbdf to
b7cf440
Compare
DhruvPareek
force-pushed
the
dp/docs-realistic-oidc-sandbox
branch
from
8983815 to
a5b170b
Compare
1 participant
Reason
The backend sandbox OTP PR adds a sandbox-only test inbox endpoint for dynamic email OTP codes. The OpenAPI and Mintlify docs need the same API surface so sandbox clients can implement the production-like OTP flow without relying on the old hardcoded
000000code.Overview
GET /sandbox/email-otps/latest.authMethodIdquery parameter.SandboxEmailOtpResponsewithauthMethodId,accountId,email,otpId,otpCode,expiresAt, andattemptsRemaining.otpCodefrom the sandbox inbox before callingPOST /auth/credentials/{id}/verify..stainless/stainless.ymland make the Stainless workflow use the repo config instead of stale hosted/generated config.openapi.yamland Mintlify OpenAPI copy.Stack
Test Plan
ruby -e 'require "yaml"; YAML.load_file(".github/workflows/stainless-action.yml"); YAML.load_file(".stainless/stainless.yml"); puts "yaml ok"'npm run build:openapinpm run lint:openapinpm run lint