Skip to content

docs: document real sandbox wallet signatures #494

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DhruvPareek wants to merge 1 commit into
base: dp/docs-realistic-sandbox-passkeys
Choose a base branch
from
+14 −9
Open

docs: document real sandbox wallet signatures #494

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions mintlify/snippets/sandbox-global-account-magic.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
The Grid sandbox lets you exercise Global Account auth flows without moving real money. Email OTP uses a sandbox test inbox. Passkey auth can use the same browser WebAuthn ceremony as production. Wallet signatures use fixed sandbox-only values. OAuth accepts OIDC ID tokens from supported providers; for isolated sandbox tests, you can also pass a JWT-shaped test token. Sandbox skips real IdP signature verification, but still validates token claims, freshness, credential identity, and verify-time nonce binding.
The Grid sandbox lets you exercise Global Account auth flows without moving real money. Email OTP uses a sandbox test inbox. Passkey auth can use the same browser WebAuthn ceremony as production, and signed wallet actions can use the same decrypted session signing key and `Grid-Wallet-Signature` stamp as production. OAuth accepts OIDC ID tokens from supported providers; for isolated sandbox tests, you can also pass a JWT-shaped test token. Sandbox skips real IdP signature verification, but still validates token claims, freshness, credential identity, and verify-time nonce binding.

Sandbox-only compatibility values are still available for some flows, but they do not exercise the production-shaped client implementation. Authentication failures return `401 UNAUTHORIZED` with a `reason` field that names the specific check that failed. A malformed OIDC JWT can return `400 INVALID_INPUT` before authentication starts.

Expand Down Expand Up @@ -123,7 +123,7 @@ curl -X POST https://api.lightspark.com/grid/2025-10-13/auth/credentials/AuthMet

### Wallet signature header

Pass `sandbox-valid-signature` as the `Grid-Wallet-Signature` HTTP header on any signed-retry flow:
After verifying an auth credential, decrypt `encryptedSessionSigningKey` with the private key matching the `clientPublicKey` you supplied on verify or refresh. Use the decrypted session signing key to build a Turnkey API-key stamp over the exact `payloadToSign` string returned by Grid, then pass that full stamp as the `Grid-Wallet-Signature` HTTP header on signed flows:

- `POST /auth/credentials` (add-additional-credential signed retry)
- `DELETE /auth/credentials/{id}` (revoke credential)
Expand All @@ -133,11 +133,17 @@ Pass `sandbox-valid-signature` as the `Grid-Wallet-Signature` HTTP header on any
- `POST /quotes/{quoteId}/execute` (when source is an embedded wallet)

```bash
STAMP=$($SIGN stamp "$SESSION_PRIV_HEX" "$PAYLOAD_TO_SIGN")
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps Bot May 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Undefined $SIGN reference in standalone snippet

The code example uses $SIGN stamp "$SESSION_PRIV_HEX" "$PAYLOAD_TO_SIGN", but $SIGN is never defined within this MDX file. In scripts/README.md it is set at line 30 (SIGN="node $(pwd)/scripts/embedded-wallet-sign.js"), so the README context is self-contained. However, this snippet is embedded in API documentation pages where a reader has no pointer to that helper script. Per the style guide, code examples should be "complete, runnable examples that users can copy and execute." A reader unfamiliar with the scripts directory will have no idea what tool to substitute for $SIGN.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: mintlify/snippets/sandbox-global-account-magic.mdx
Line: 136

Comment:
**Undefined `$SIGN` reference in standalone snippet**

The code example uses `$SIGN stamp "$SESSION_PRIV_HEX" "$PAYLOAD_TO_SIGN"`, but `$SIGN` is never defined within this MDX file. In `scripts/README.md` it is set at line 30 (`SIGN="node $(pwd)/scripts/embedded-wallet-sign.js"`), so the README context is self-contained. However, this snippet is embedded in API documentation pages where a reader has no pointer to that helper script. Per the style guide, code examples should be "complete, runnable examples that users can copy and execute." A reader unfamiliar with the scripts directory will have no idea what tool to substitute for `$SIGN`.

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

Fix in Claude Code


curl -X POST https://api.lightspark.com/grid/2025-10-13/quotes/Quote:abc123/execute \
-u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21" \
-H "Grid-Wallet-Signature: sandbox-valid-signature"
-H "Grid-Wallet-Signature: $STAMP"
```

Any other header value returns `401 UNAUTHORIZED` with `reason: "Invalid Grid-Wallet-Signature"`.
Sandbox validates that the stamp is a P-256 Turnkey API-key stamp over the exact pending Turnkey payload and that the public key belongs to an active sandbox session for the wallet.

<Note>
The legacy sandbox-only `Grid-Wallet-Signature: sandbox-valid-signature` value is still accepted for compatibility. Use a real session stamp when you want the client implementation to match production.
</Note>
9 changes: 4 additions & 5 deletions scripts/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,11 +258,10 @@ g -X POST -H 'Content-Type: application/json' \
"$GRID_BASE_URL/quotes/$QUOTE_ID/execute" | jq '.status'
```

> **Sandbox tip**: in sandbox mode you can skip the keypair / decrypt /
> stamp dance entirely. Use the fixed value
> `Grid-Wallet-Signature: sandbox-valid-signature`; any other value is
> rejected with the same `INVALID_INPUT` shape a bad real stamp would
> produce.
> **Sandbox tip**: sandbox accepts the same decrypted session signing key and
> `Grid-Wallet-Signature` stamp shape as production. The legacy fixed value
> `Grid-Wallet-Signature: sandbox-valid-signature` is still accepted for
> compatibility, but it does not exercise the production-shaped client path.

```bash
# Poll — typically 60–180s for the full chain to reach COMPLETED.
Expand Down
Loading