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

[DhruvPareek]

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.
Learn more

• 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

Edit this comment to update them. They will appear in their respective SDK's changelogs.

✅ grid-kotlin studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

✅ grid-openapi studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅

✅ grid-typescript studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ❗ → lint ❗ → test ❗

✅ grid-python studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

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

---

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-08 20:58:59 UTC

[greptile-apps]

Greptile Summary

This PR corrects the requestId format across all OpenAPI schemas, path definitions, bundled specs, and Mintlify documentation snippets to match the LSID pattern (Request:<uuid>) that Sparkcore actually returns from get_pending_request_lsid. Descriptions are also tightened to say "echo this value exactly."

• All Request-Id header examples, response body requestId fields, and prose descriptions are updated consistently across the source YAML files and their regenerated bundles.
• The payloadToSign JSON string examples in auth_credentials.yaml and authentication.mdx still embed the old plain-UUID requestId internally — worth confirming whether the real server payload also uses the Request:<uuid> form so those strings stay in sync.

Confidence Score: 4/5

Safe to merge; changes are documentation-only and the format alignment is correct across the vast majority of examples.

The payloadToSign JSON string in two places retains the old plain-UUID requestId while every other example has been updated to the Request: LSID format. If the backend embeds the LSID inside the actual payload, those two examples will silently mislead developers inspecting what they are signing.

openapi/paths/auth/auth_credentials.yaml and mintlify/snippets/global-accounts/authentication.mdx both retain a plain-UUID requestId inside the payloadToSign JSON string example.

Important Files Changed

Filename	Overview
openapi/components/schemas/common/SignedRequestChallenge.yaml	Updated requestId description and example to use Request: LSID format; clean change.
openapi/components/schemas/auth/PasskeyAuthChallenge.yaml	Updated requestId description and example to Request: format to match LSID; consistent with schema peer.
openapi/paths/auth/auth_credentials.yaml	Header example updated to Request: and response requestId examples updated, but the payloadToSign JSON string still embeds the old plain-UUID requestId internally.
mintlify/snippets/global-accounts/authentication.mdx	Request-Id header and top-level requestId field examples updated correctly, but the payloadToSign JSON string in the EMAIL_OTP example still embeds the old plain-UUID requestId.
openapi/paths/auth/auth_credentials_{id}_challenge.yaml	Response body requestId example updated to Request:; minimal change.
openapi/paths/auth/auth_credentials_{id}_verify.yaml	Header example and description updated to Request:; clean change.
mintlify/snippets/sandbox-global-account-magic.mdx	All three sandbox curl examples updated to Request: in the Request-Id header; complete and consistent.

Sequence Diagram

sequenceDiagram
    participant Client
    participant GridAPI as Grid API

    Client->>GridAPI: "POST /auth/credentials/{id} (initial)"
    GridAPI-->>Client: 202 Challenge with payloadToSign and requestId as Request:uuid

    Note over Client: Sign payloadToSign with session API keypair

    Client->>GridAPI: POST signed retry with Request-Id: Request:uuid and Grid-Wallet-Signature
    GridAPI-->>Client: 200 OK credential registered

Loading

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/paths/auth/auth_credentials.yaml:144-145
The `requestId` inside the `payloadToSign` JSON string example was not updated to the `Request:<uuid>` format, while the surrounding `requestId` field was. If the server-generated payload embeds the full LSID (which is expected given the PR description — Sparkcore returns `Request:<uuid>` from `get_pending_request_lsid`), a developer comparing the embedded value against the top-level `requestId` field will see a confusing format mismatch in the documentation.

```suggestion
                payloadToSign: '{"requestId":"Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21","type":"EMAIL_OTP","accountId":"InternalAccount:01HF3Z4QWERTY","expiresAt":"2026-04-08T15:35:00Z"}'
                requestId: Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21
```

### Issue 2 of 2
mintlify/snippets/global-accounts/authentication.mdx:590-591
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",
```

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

[greptile-apps]

The requestId inside the payloadToSign JSON string example was not updated to the Request:<uuid> format, while the surrounding requestId field was. If the server-generated payload embeds the full LSID (which is expected given the PR description — Sparkcore returns Request:<uuid> from get_pending_request_lsid), a developer comparing the embedded value against the top-level requestId field will see a confusing format mismatch in the documentation.

Suggested change

	payloadToSign: '{"requestId":"7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21","type":"EMAIL_OTP","accountId":"InternalAccount:01HF3Z4QWERTY","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":"InternalAccount:01HF3Z4QWERTY","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: openapi/paths/auth/auth_credentials.yaml
Line: 144-145

Comment:
The `requestId` inside the `payloadToSign` JSON string example was not updated to the `Request:<uuid>` format, while the surrounding `requestId` field was. If the server-generated payload embeds the full LSID (which is expected given the PR description — Sparkcore returns `Request:<uuid>` from `get_pending_request_lsid`), a developer comparing the embedded value against the top-level `requestId` field will see a confusing format mismatch in the documentation.

```suggestion
                payloadToSign: '{"requestId":"Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21","type":"EMAIL_OTP","accountId":"InternalAccount:01HF3Z4QWERTY","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.

[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.