lightsparkdev · DhruvPareek · May 19, 2026
diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml
diff --git a/mintlify/snippets/global-accounts/authentication.mdx b/mintlify/snippets/global-accounts/authentication.mdx
@@ -562,7 +562,7 @@ Key rules:
 - Always sign the `payloadToSign` **byte-for-byte as Grid returned it**. Do not re-parse, re-serialize, or modify whitespace.
 - Sign with the **session private key** held on the client — never ship it back to your backend.
 - The retry must reach Grid before `expiresAt` (typically 5 minutes from issue).
-- The `requestId` is single-use; reusing one yields `401`.
+- The `requestId` is returned as `Request:<uuid>` and is single-use; reusing one yields `401`.
 
 ### Add an additional credential
 
@@ -585,8 +585,8 @@ Requires an active session on an *existing* credential on the same account. The
     ```json
     {
       "type": "EMAIL_OTP",
-      "payloadToSign": "{\"requestId\":\"7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21\",\"type\":\"EMAIL_OTP\",\"accountId\":\"InternalAccount:019542f5-b3e7-1d02-0000-000000000002\",\"expiresAt\":\"2026-04-08T15:35:00Z\"}",
-      "requestId": "7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21",
+      "payloadToSign": "{\"organizationId\":\"org_2m9F...\",\"parameters\":{\"userEmail\":\"jane@example.com\",\"userId\":\"user_2m9F...\"},\"timestampMs\":\"1775681700000\",\"type\":\"ACTIVITY_TYPE_UPDATE_USER_EMAIL\"}",
+      "requestId": "Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21",
       "expiresAt": "2026-04-08T15:35:00Z"
     }
     ```
@@ -602,7 +602,7 @@ Requires an active session on an *existing* credential on the same account. The
       -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
       -H "Content-Type: application/json" \
       -H "Grid-Wallet-Signature: MEUCIQDx7k2N0aK4p8f3vR9J6yT5wL1mB0sXnG2hQ4vJ8zYkCgIgZ4rP9dT7eWfU3oM6KjR1qSpNvBwL0tXyA2iG8fH5dE=" \
-      -H "Request-Id: 7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21" \
+      -H "Request-Id: Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21" \
       -d '{
         "type": "EMAIL_OTP",
         "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
@@ -636,8 +636,8 @@ A credential is revoked by signing with a session from **a different credential
     ```json
     {
       "type": "PASSKEY",
-      "payloadToSign": "Y2hhbGxlbmdlLXBheWxvYWQtdG8tc2lnbg==",
-      "requestId": "9f7a2c10-5e88-4fb1-bd0e-1c3a8e7b2d45",
+      "payloadToSign": "{\"organizationId\":\"org_2m9F...\",\"parameters\":{\"authenticatorIds\":[\"authenticator_2m9F...\"],\"userId\":\"user_2m9F...\"},\"timestampMs\":\"1775681700000\",\"type\":\"ACTIVITY_TYPE_DELETE_AUTHENTICATORS\"}",
+      "requestId": "Request:9f7a2c10-5e88-4fb1-bd0e-1c3a8e7b2d45",
       "expiresAt": "2026-04-08T15:35:00Z"
     }
     ```
@@ -650,7 +650,7 @@ A credential is revoked by signing with a session from **a different credential
     curl -X DELETE "$GRID_BASE_URL/auth/credentials/AuthMethod:019542f5-b3e7-1d02-0000-000000000001" \
       -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
       -H "Grid-Wallet-Signature: MEUCIQDx7k2N0aK4p8f3vR9J6yT5wL1mB0sXnG2hQ4vJ8zYkCgIgZ4rP9dT7eWfU3oM6KjR1qSpNvBwL0tXyA2iG8fH5dE=" \
-      -H "Request-Id: 9f7a2c10-5e88-4fb1-bd0e-1c3a8e7b2d45"
+      -H "Request-Id: Request:9f7a2c10-5e88-4fb1-bd0e-1c3a8e7b2d45"
     ```
 
     **Response:** `204 No Content`. All active sessions issued by the revoked credential are also revoked.

diff --git a/mintlify/snippets/global-accounts/exporting-wallet.mdx b/mintlify/snippets/global-accounts/exporting-wallet.mdx
@@ -25,7 +25,7 @@ sequenceDiagram
   <Step title="First call — receive the challenge">
     ```bash
     curl -X POST "$GRID_BASE_URL/internal-accounts/InternalAccount:019542f5-b3e7-1d02-0000-000000000002/export" \
-      -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"
+      -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
       -H "Content-Type: application/json" \
       -d '{
         "clientPublicKey": "04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2"
@@ -36,8 +36,8 @@ sequenceDiagram
 
     ```json
     {
-      "payloadToSign": "Y2hhbGxlbmdlLXBheWxvYWQtdG8tc2lnbg==",
-      "requestId": "c3f8a614-47e2-4a19-9f5d-2b0a91d47e08",
+      "payloadToSign": "{\"organizationId\":\"org_2m9F...\",\"parameters\":{\"targetPublicKey\":\"04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2\",\"walletId\":\"wallet_2m9F...\"},\"timestampMs\":\"1775681700000\",\"type\":\"ACTIVITY_TYPE_EXPORT_WALLET\"}",
+      "requestId": "Request:c3f8a614-47e2-4a19-9f5d-2b0a91d47e08",
       "expiresAt": "2026-04-19T12:10:00Z"
     }
     ```
@@ -51,7 +51,7 @@ sequenceDiagram
       -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
       -H "Content-Type: application/json" \
       -H "Grid-Wallet-Signature: MEUCIQDx7k2N0aK4p8f3vR9J6yT5wL1mB0sXnG2hQ4vJ8zYkCgIgZ4rP9dT7eWfU3oM6KjR1qSpNvBwL0tXyA2iG8fH5dE=" \
-      -H "Request-Id: c3f8a614-47e2-4a19-9f5d-2b0a91d47e08" \
+      -H "Request-Id: Request:c3f8a614-47e2-4a19-9f5d-2b0a91d47e08" \
       -d '{
         "clientPublicKey": "04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2"
       }'

diff --git a/mintlify/snippets/global-accounts/managing-sessions.mdx b/mintlify/snippets/global-accounts/managing-sessions.mdx
@@ -52,8 +52,8 @@ Session revocation uses the same <a href="authentication#the-signed-retry-patter
     ```json
     {
       "type": "PASSKEY",
-      "payloadToSign": "Y2hhbGxlbmdlLXBheWxvYWQtdG8tc2lnbg==",
-      "requestId": "2b1e5a08-9c44-4e91-ae7f-6d0b3f8c1e22",
+      "payloadToSign": "{\"organizationId\":\"org_2m9F...\",\"parameters\":{\"apiKeyIds\":[\"api_key_2m9F...\"],\"userId\":\"user_2m9F...\"},\"timestampMs\":\"1775681700000\",\"type\":\"ACTIVITY_TYPE_DELETE_API_KEYS\"}",
+      "requestId": "Request:2b1e5a08-9c44-4e91-ae7f-6d0b3f8c1e22",
       "expiresAt": "2026-04-19T12:10:00Z"
     }
     ```
@@ -66,7 +66,7 @@ Session revocation uses the same <a href="authentication#the-signed-retry-patter
     curl -X DELETE "$GRID_BASE_URL/auth/sessions/Session:019542f5-b3e7-1d02-0000-000000000003" \
       -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
       -H "Grid-Wallet-Signature: MEUCIQDx7k2N0aK4p8f3vR9J6yT5wL1mB0sXnG2hQ4vJ8zYkCgIgZ4rP9dT7eWfU3oM6KjR1qSpNvBwL0tXyA2iG8fH5dE=" \
-      -H "Request-Id: 2b1e5a08-9c44-4e91-ae7f-6d0b3f8c1e22"
+      -H "Request-Id: Request:2b1e5a08-9c44-4e91-ae7f-6d0b3f8c1e22"
     ```
 
     **Response:** `204 No Content`.

diff --git a/openapi.yaml b/openapi.yaml
diff --git a/openapi/components/schemas/common/SignedRequestChallenge.yaml b/openapi/components/schemas/common/SignedRequestChallenge.yaml
@@ -21,7 +21,7 @@ properties:
       then send the full base64url-encoded stamp in
       `Grid-Wallet-Signature` on the retry that completes the original
       request.
-    example: Y2hhbGxlbmdlLXBheWxvYWQtdG8tc2lnbg==
+    example: '{"organizationId":"org_2m9F...","parameters":{"userId":"user_2m9F..."},"timestampMs":"1775681700000","type":"ACTIVITY_TYPE_EXAMPLE"}'
   requestId:
     type: string
     description: >-

diff --git a/openapi/paths/auth/auth_credentials.yaml b/openapi/paths/auth/auth_credentials.yaml
@@ -141,21 +141,21 @@ post:
               summary: Additional email OTP credential challenge
               value:
                 type: EMAIL_OTP
-                payloadToSign: '{"requestId":"Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21","type":"EMAIL_OTP","accountId":"InternalAccount:01HF3Z4QWERTY","expiresAt":"2026-04-08T15:35:00Z"}'
+                payloadToSign: '{"organizationId":"org_2m9F...","parameters":{"userEmail":"jane@example.com","userId":"user_2m9F..."},"timestampMs":"1775681700000","type":"ACTIVITY_TYPE_UPDATE_USER_EMAIL"}'
                 requestId: Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21
                 expiresAt: '2026-04-08T15:35:00Z'
             oauth:
               summary: Additional OAuth credential challenge
               value:
                 type: OAUTH
-                payloadToSign: Y2hhbGxlbmdlLXBheWxvYWQtdG8tc2lnbg==
+                payloadToSign: '{"organizationId":"org_2m9F...","parameters":{"oauthProviders":[{"oidcToken":"eyJhbGciOiJSUzI1NiIsImtpZCI6ImFiYzEyMyIsInR5cCI6IkpXVCJ9...","providerName":"Google"}],"userId":"user_2m9F..."},"timestampMs":"1775681700000","type":"ACTIVITY_TYPE_CREATE_OAUTH_PROVIDERS"}'
                 requestId: Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21
                 expiresAt: '2026-04-08T15:35:00Z'
             passkey:
               summary: Additional passkey credential challenge
               value:
                 type: PASSKEY
-                payloadToSign: Y2hhbGxlbmdlLXBheWxvYWQtdG8tc2lnbg==
+                payloadToSign: '{"organizationId":"org_2m9F...","parameters":{"authenticators":[{"attestation":{"attestationObject":"o2NmbXRk...","clientDataJson":"eyJjaGFsbGVuZ2UiOiJBcktRa...","credentialId":"AdKXJEch1aV5Wo7bj7qLHskVY4OoNaj9qu8TPdJ7kSAgUeRxWNngXlcNIGt4gexZGKVGcqZpqqWordXb_he1izY"},"authenticatorName":"iPhone Face-ID","challenge":"ArkQi2yAYHPlgnJNFBlneIwchQdWXBOTrdB-AmMUB21Lx","transports":["internal","hybrid"]}],"userId":"user_2m9F..."},"timestampMs":"1775681700000","type":"ACTIVITY_TYPE_CREATE_AUTHENTICATORS_V2"}'
                 requestId: Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21
                 expiresAt: '2026-04-08T15:35:00Z'
     '400':

diff --git a/openapi/paths/customers/customers_{customerId}.yaml b/openapi/paths/customers/customers_{customerId}.yaml
@@ -172,7 +172,7 @@ patch:
             embeddedWalletEmailUpdate:
               summary: Embedded Wallet customer email update challenge
               value:
-                payloadToSign: '{"requestId":"Request:019542f5-b3e7-1d02-0000-000000000010","customerId":"Customer:019542f5-b3e7-1d02-0000-000000000001","email":"john.smith@example.com","credentialIds":["AuthMethod:019542f5-b3e7-1d02-0000-000000000101","AuthMethod:019542f5-b3e7-1d02-0000-000000000102"],"expiresAt":"2026-04-08T15:35:00Z"}'
+                payloadToSign: '{"organizationId":"org_2m9F...","parameters":{"userEmail":"john.smith@example.com","userId":"user_2m9F..."},"timestampMs":"1775681700000","type":"ACTIVITY_TYPE_UPDATE_USER_EMAIL"}'
                 requestId: Request:019542f5-b3e7-1d02-0000-000000000010
                 expiresAt: '2026-04-08T15:35:00Z'
     '400':

diff --git a/openapi/paths/internal_accounts/internal_accounts_{id}.yaml b/openapi/paths/internal_accounts/internal_accounts_{id}.yaml
@@ -108,7 +108,7 @@ patch:
             challenge:
               summary: Internal account update challenge
               value:
-                payloadToSign: Y2hhbGxlbmdlLXBheWxvYWQtdG8tc2lnbg==
+                payloadToSign: '{"organizationId":"org_2m9F...","parameters":{"encoding":"PAYLOAD_ENCODING_HEXADECIMAL","hashFunction":"HASH_FUNCTION_NO_OP","payload":"9f3b...","signWith":"sp1q..."},"timestampMs":"1775681700000","type":"ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2"}'
                 requestId: Request:019542f5-b3e7-1d02-0000-000000000010
                 expiresAt: '2026-04-08T15:35:00Z'
     '400':