docs: document Global Account sandbox magic values #405
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| The Grid sandbox accepts a small set of magic values that bypass real auth and credential checks for Global Account flows, so you can exercise the full request shape without standing up Turnkey, WebAuthn, or an OIDC provider. These values are sandbox-only — production enforces real signature verification, WebAuthn assertion, and OIDC nonce binding. | ||
|
|
||
| A wrong magic value (or any other value) returns `401 UNAUTHORIZED` with a `reason` field that names the specific check that failed. | ||
|
|
||
| ### Email OTP code | ||
|
|
||
| Pass `000000` as the body `otp` on `POST /auth/credentials/{id}/verify` when the credential type is `EMAIL_OTP`. The sandbox skips OTP delivery and accepts this value as a valid response to the issued challenge. | ||
|
|
||
| ```bash | ||
| 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" \ | ||
| -H "Request-Id: 7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21" \ | ||
| -d '{ | ||
| "type": "EMAIL_OTP", | ||
| "otp": "000000", | ||
| "clientPublicKey": "04f45f2a..." | ||
| }' | ||
| ``` | ||
|
|
||
| Any other code returns `401 UNAUTHORIZED` with `reason: "Invalid OTP code"`. | ||
|
|
||
| ### Passkey assertion signature | ||
|
|
||
| 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. | ||
|
|
||
| ```bash | ||
| 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" \ | ||
| -H "Request-Id: 7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21" \ | ||
| -d '{ | ||
| "type": "PASSKEY", | ||
| "assertion": { | ||
| "credentialId": "...", | ||
| "clientDataJson": "...", | ||
| "authenticatorData": "...", | ||
| "signature": "sandbox-valid-passkey-signature" | ||
| }, | ||
| "clientPublicKey": "04f45f2a..." | ||
| }' | ||
| ``` | ||
|
|
||
| Any other signature returns `401 UNAUTHORIZED` with `reason: "Invalid passkey signature"`. `clientPublicKey` is still required — the magic value bypasses the credential check, not the HPKE plumbing that seals the session signing key to the public key you supply. | ||
|
|
||
| ### OAuth (OIDC) token | ||
|
|
||
| Pass `sandbox-valid-oidc-token` as the body `oidcToken` on both `POST /auth/credentials` (OAUTH create) and `POST /auth/credentials/{id}/verify` (OAUTH). | ||
|
|
||
| ```bash | ||
| 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" \ | ||
| -H "Request-Id: 7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21" \ | ||
| -d '{ | ||
| "type": "OAUTH", | ||
| "oidcToken": "sandbox-valid-oidc-token", | ||
| "clientPublicKey": "04f45f2a..." | ||
| }' | ||
| ``` | ||
|
Comment on lines
+50
to
+60
Contributor
There was a problem hiding this comment.
The section states the magic value applies to both Prompt To Fix With AIThis is a comment left during a code review.
Path: mintlify/snippets/sandbox-global-account-magic.mdx
Line: 50-60
Comment:
**Missing curl example for OAUTH create flow**
The section states the magic value applies to both `POST /auth/credentials` (OAUTH create) and verify, but only provides a curl example for the verify endpoint. Given that the Note flags a meaningful gotcha for the create path (requiring a JWT-shaped token), a companion example showing how to construct the dummy JWT for create would substantially help developers avoid confusion.
How can I resolve this? If you propose a fix, please make it concise. |
||
|
|
||
| Any other token returns `401 UNAUTHORIZED` with `reason: "Invalid OIDC token"`. | ||
|
|
||
| <Note> | ||
| **OAUTH create still requires a JWT-shaped token.** On the initial `POST /auth/credentials` (OAUTH create), the `oidcToken` must be a structurally valid JWT (`header.payload.signature`) so Grid can decode the `iss` claim and resolve the provider name. The literal `sandbox-valid-oidc-token` works on `verify` but not on `create` — for `create`, sign your own dummy JWT with any payload that includes a recognized `iss` claim. The sandbox bypasses signature verification, not JWT structure parsing. | ||
| </Note> | ||
|
|
||
| ### Wallet signature header | ||
|
|
||
| Pass `sandbox-valid-signature` as the `Grid-Wallet-Signature` HTTP header on any signed-retry flow: | ||
|
|
||
| - `POST /auth/credentials` (add-additional-credential signed retry) | ||
| - `DELETE /auth/credentials/{id}` (revoke credential) | ||
| - `DELETE /auth/sessions/{id}` (revoke session) | ||
| - `POST /internal-accounts/{id}/export` (export wallet) | ||
| - `POST /quotes/{quoteId}/execute` (when source is an embedded wallet) | ||
|
|
||
| ```bash | ||
| 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" | ||
| ``` | ||
|
|
||
| Any other header value returns `401 UNAUTHORIZED` with `reason: "Invalid Grid-Wallet-Signature"`. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The opening sentence says
sandbox-valid-oidc-tokenworks on bothPOST /auth/credentials(OAUTH create) and verify, but the Note immediately below corrects this and states it does not work for create — a properly structured JWT is required there. A developer reading the first sentence and using the magic value for the create call will get a401 UNAUTHORIZEDwithout any obvious reason until they read the Note carefully.Consider updating the opening sentence to be accurate upfront, for example:
Prompt To Fix With AI