docs: document realistic sandbox passkeys

Author: DhruvPareek

mintlify/openapi.yaml

@@ -1,6 +1,6 @@
-The Grid sandbox accepts a small set of test helpers for Global Account flows, so you can exercise the full request shape without real OTP delivery, WebAuthn ceremony, or wallet signatures. Email OTP uses a sandbox test inbox. Passkey and 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.
 
-A wrong magic value or sandbox OIDC authentication failure returns `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.
+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.
 
 ### Email OTP code
 
@@ -24,11 +24,17 @@ curl -X POST "$GRID_BASE_URL/auth/credentials/AuthMethod:abc123/verify" \
 
 The sandbox validates the code against the pending OTP state. A wrong, expired, consumed, or locked-out code returns `401 UNAUTHORIZED`.
 
-### Passkey assertion signature
+### Passkey WebAuthn ceremony
 
-Pass `sandbox-valid-passkey-signature` as `assertion.signature` on `POST /auth/credentials/{id}/verify` when the credential type is `PASSKEY`. The sandbox accepts the rest of the assertion as-is and skips the WebAuthn signature check.
+For new sandbox integrations, use the same WebAuthn calls you plan to use in production.
 
-Passkey reauthentication is a two-step `/challenge` → `/verify` flow. The `clientPublicKey` is sent on `/challenge` (so Grid can seal the session signing key to your device) — the magic value bypasses the credential check, not the HPKE plumbing, so the public key is still required.
+1. Generate your own WebAuthn registration challenge and call `navigator.credentials.create()`.
+2. Register the passkey with `POST /auth/credentials`, passing the challenge and attestation returned by the browser.
+3. Reauthenticate with `POST /auth/credentials/{id}/challenge`, passing the P-256 `clientPublicKey` that Grid should seal the session signing key to.
+4. Pass the returned `challenge` into `navigator.credentials.get()` using the returned `credentialId` in `allowCredentials`.
+5. Verify with `POST /auth/credentials/{id}/verify`, passing the browser assertion and echoing `Request-Id` from the challenge response.
+
+The sandbox validates the registered credential ID, WebAuthn challenge, origin/RP binding, user-presence bit, assertion signature, and signature counter. A successful verify response includes `encryptedSessionSigningKey`, sealed to the `clientPublicKey`, just like production.
 
 ```bash
 # 1. /challenge with clientPublicKey
@@ -39,7 +45,7 @@ curl -X POST https://api.lightspark.com/grid/2025-10-13/auth/credentials/AuthMet
     "clientPublicKey": "04f45f2a..."
   }'
 
-# 2. /verify with the magic signature, no clientPublicKey
+# 2. /verify with the browser assertion returned by navigator.credentials.get()
 curl -X POST https://api.lightspark.com/grid/2025-10-13/auth/credentials/AuthMethod:abc123/verify \
   -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
   -H "Content-Type: application/json" \
@@ -50,12 +56,14 @@ curl -X POST https://api.lightspark.com/grid/2025-10-13/auth/credentials/AuthMet
       "credentialId": "...",
       "clientDataJson": "...",
       "authenticatorData": "...",
-      "signature": "sandbox-valid-passkey-signature"
+      "signature": "..."
     }
   }'
 ```
 
-Any other signature returns `401 UNAUTHORIZED` with `reason: "Invalid passkey signature"`.
+<Note>
+  The legacy sandbox-only assertion signature `sandbox-valid-passkey-signature` is still accepted for compatibility, but it skips WebAuthn verification and should not be used for production-shaped sandbox tests.
+</Note>
 
 ### OAuth (OIDC) token
 
@@ -115,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)
@@ -125,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.
+
+<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>

mintlify/snippets/sandbox-global-account-magic.mdx

@@ -1,5 +1,10 @@
 title: Passkey Assertion
 type: object
+description: >-
+  WebAuthn assertion returned by `navigator.credentials.get()`. In sandbox,
+  Grid validates the assertion against the registered passkey credential so the
+  client-side flow can match production. In production, Turnkey validates the
+  WebAuthn assertion.
 required:
   - credentialId
   - clientDataJson

openapi.yaml

@@ -180,8 +180,9 @@ g -X POST -H 'Content-Type: application/json' -d '{}' \
 
 Read the OTP code from the email and assign to `$OTP`.
 
-> **Sandbox tip**: in sandbox mode, no email is sent — verify with the fixed
-> OTP code `000000`.
+> **Sandbox tip**: in sandbox mode, no email is sent. Fetch the active code
+> from `GET /sandbox/email-otps/latest?authMethodId=$CRED_ID`, then assign
+> the returned `otpCode` to `$OTP`.
 
 ### 3.3 Verify the OTP and decrypt the session key
 
@@ -255,11 +256,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.