From 304ae01d44a7f9ada0c8df3aad15002f716acc08 Mon Sep 17 00:00:00 2001 From: Dhruv Pareek Date: Fri, 22 May 2026 17:13:08 -0700 Subject: [PATCH] docs: document real sandbox wallet signatures --- mintlify/snippets/sandbox-global-account-magic.mdx | 14 ++++++++++---- scripts/README.md | 9 ++++----- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/mintlify/snippets/sandbox-global-account-magic.mdx b/mintlify/snippets/sandbox-global-account-magic.mdx index a988cd3d..0b4043b1 100644 --- a/mintlify/snippets/sandbox-global-account-magic.mdx +++ b/mintlify/snippets/sandbox-global-account-magic.mdx @@ -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. @@ -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) @@ -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") + 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. + + + 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. + diff --git a/scripts/README.md b/scripts/README.md index d7d216e1..17914170 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -255,11 +255,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.