Align signed request id examples

[DhruvPareek]

Summary

• Align signed-retry requestId examples with the Request:<uuid> LSID format returned by Sparkcore handlers.
• Update shared challenge schemas, signed-retry header examples, and Global Accounts snippets to tell clients to echo the challenge requestId exactly.
• Regenerate the bundled OpenAPI specs.

Validation

• npm run lint:openapi
• git diff --check

Notes

• Sparkcore handlers issue pending request IDs via get_pending_request_lsid(...), so signed retries should use the returned Request:<uuid> value in Request-Id.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ready	Preview, Comment	May 12, 2026 6:47pm

[DhruvPareek]

• Align signed request id examples #453 👈 (View in Graphite)
• Add wallet privacy endpoint to OpenAPI #452
• Add auth session refresh endpoints #451
• Add OTP email update endpoint to OpenAPI #450
• Add passkey credentialId to auth challenge response #449
• Add passkey credentialId to auth credential list #448
• Align auth session request-id contract #445 : 1 other dependent PR (#446 )
• Align auth credential create contract #444
• main

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

[github-actions]

✱ Stainless preview builds for grid

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

kotlin

docs(api): clarify requestId format in auth challenge models

openapi

docs(api): clarify requestId format and usage in auth endpoints

python

docs(api): clarify request_id format in auth challenge models

typescript

docs(api): clarify Request-Id header format across auth and customers

⚠️ grid-python studio · code

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

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

⚠️ grid-kotlin studio · code

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

⚠️ grid-openapi studio · code

Your SDK build had at least one "error" diagnostic.
generate ❗

⚠️ grid-typescript 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 ❗

---

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-05-12 20:11:09 UTC

[greptile-apps]

Greptile Summary

This PR updates all requestId examples and descriptions across the OpenAPI source files and regenerated bundled specs to use the Request:<uuid> LSID format that Sparkcore handlers actually return, rather than bare UUIDs. Descriptions are also clarified to instruct clients to echo the value exactly.

• Updated SignedRequestChallenge and PasskeyAuthChallenge shared schemas, plus every signed-retry Request-Id header example across six path files (auth_credentials, auth_credentials_{id}, auth_credentials_{id}_challenge, auth_credentials_{id}_verify, auth_sessions_{id}, internal_accounts_{id}_export).
• The EMAIL_OTP payloadToSign JSON string example was also updated so the embedded requestId matches the Request:<uuid> format, keeping both fields consistent.
• Both bundled specs (openapi.yaml and mintlify/openapi.yaml) were regenerated to reflect all source changes.

Confidence Score: 5/5

This is a documentation-only change updating example values and descriptions; no runtime logic is modified.

All changed files are OpenAPI YAML spec sources and their regenerated bundles. The update is purely cosmetic — renaming example strings from bare UUIDs to the Request:<uuid> format and clarifying description prose. No code paths, validation logic, or server behaviour are touched.

No files require special attention.

Important Files Changed

Filename	Overview
openapi/components/schemas/common/SignedRequestChallenge.yaml	Updated requestId description and example to Request:<uuid> LSID format; consistent and accurate.
openapi/components/schemas/auth/PasskeyAuthChallenge.yaml	Updated passkey requestId description and example to Request:<uuid> format; aligns with shared schema change.
openapi/paths/auth/auth_credentials.yaml	Updated Request-Id header example and all challenge response examples (EMAIL_OTP payloadToSign + top-level requestId, OAUTH, PASSKEY) to Request:<uuid> format.
openapi/paths/auth/auth_credentials_{id}.yaml	Updated Request-Id header example for credential deletion signed retry to Request:<uuid> format.
openapi/paths/auth/auth_credentials_{id}_challenge.yaml	Updated passkey challenge response requestId example to Request:<uuid> format.
openapi/paths/auth/auth_credentials_{id}_verify.yaml	Updated Request-Id header example for passkey verify signed retry to Request:<uuid> format.
openapi/paths/auth/auth_sessions_{id}.yaml	Updated Request-Id header example for session deletion signed retry to Request:<uuid> format.
openapi/paths/internal_accounts/internal_accounts_{id}_export.yaml	Updated Request-Id header example for account export signed retry to Request:<uuid> format.
openapi.yaml	Bundled spec regenerated from sources; all requestId examples and descriptions consistently updated to Request:<uuid> format.
mintlify/openapi.yaml	Bundled Mintlify spec regenerated; all requestId examples and descriptions consistently updated to Request:<uuid> format, including the payloadToSign JSON string for EMAIL_OTP.

Sequence Diagram

sequenceDiagram
    participant C as Client
    participant G as Grid API (Sparkcore)

    C->>G: POST /auth/credentials (initial attempt)
    G-->>C: "202 Challenge { requestId: "Request:<uuid>", payloadToSign: "..." }"

    Note over C: Sign payloadToSign with wallet key

    C->>G: "POST /auth/credentials<br/>Request-Id: Request:<uuid><br/>Grid-Wallet-Signature: <sig>"
    G-->>C: 200 OK (credential registered)

Loading

_{Reviews (2): Last reviewed commit: "Align signed request id examples" | Re-trigger Greptile}

[greptile-apps]

Same payloadToSign inconsistency as in the OpenAPI source: the requestId embedded inside the JSON string still uses the old plain-UUID format while the surrounding requestId field has been updated to Request:<uuid>. If the backend includes the LSID in the payload, this example will mislead developers comparing the two values.

Suggested change

	"payloadToSign": "{\"requestId\":\"7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21\",\"type\":\"EMAIL_OTP\",\"accountId\":\"EmbeddedWallet:019542f5-b3e7-1d02-0000-000000000002\",\"expiresAt\":\"2026-04-08T15:35:00Z\"}",
	"requestId": "7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21",
	"requestId": "Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21",
	"payloadToSign": "{\"requestId\":\"Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21\",\"type\":\"EMAIL_OTP\",\"accountId\":\"EmbeddedWallet:019542f5-b3e7-1d02-0000-000000000002\",\"expiresAt\":\"2026-04-08T15:35:00Z\"}",
	"requestId": "Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21",

Prompt To Fix With AI

This is a comment left during a code review.
Path: mintlify/snippets/global-accounts/authentication.mdx
Line: 590-591

Comment:
Same `payloadToSign` inconsistency as in the OpenAPI source: the `requestId` embedded inside the JSON string still uses the old plain-UUID format while the surrounding `requestId` field has been updated to `Request:<uuid>`. If the backend includes the LSID in the payload, this example will mislead developers comparing the two values.

```suggestion
      "payloadToSign": "{\"requestId\":\"Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21\",\"type\":\"EMAIL_OTP\",\"accountId\":\"EmbeddedWallet:019542f5-b3e7-1d02-0000-000000000002\",\"expiresAt\":\"2026-04-08T15:35:00Z\"}",
      "requestId": "Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21",
```

How can I resolve this? If you propose a fix, please make it concise.

[restamp-bot]

f6261de is a pure rebase onto c4d67f3. Approving based on @pengying's previous approval of bdb04c8.

[restamp-bot]

fc07e2b is a pure rebase onto 6d01216. Approving based on @pengying's previous approval of bdb04c8.

The base branch was changed.

[DhruvPareek]

Merge activity

• May 12, 8:03 PM UTC: @DhruvPareek merged this pull request with Graphite.