diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 991c63ec..c0376af8 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -704,7 +704,7 @@ paths: 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': @@ -3833,7 +3833,7 @@ paths: 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': @@ -4054,21 +4054,21 @@ paths: 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': @@ -9211,7 +9211,7 @@ components: payloadToSign: type: string description: Canonical payload for the retry authorization stamp. Build an API-key stamp over this exact value with the session API keypair, 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: Grid-issued `Request:` identifier for this pending request. Echo this value exactly in the `Request-Id` header on the signed retry so the server can correlate the retry with the issued challenge. diff --git a/mintlify/snippets/global-accounts/authentication.mdx b/mintlify/snippets/global-accounts/authentication.mdx index 05f4d45b..881fbfa3 100644 --- a/mintlify/snippets/global-accounts/authentication.mdx +++ b/mintlify/snippets/global-accounts/authentication.mdx @@ -567,7 +567,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:` and is single-use; reusing one yields `401`. ### Add an additional credential @@ -590,7 +590,7 @@ Requires an active session on an *existing* credential on the same account. The ```json { "type": "EMAIL_OTP", - "payloadToSign": "{\"requestId\":\"Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21\",\"type\":\"EMAIL_OTP\",\"accountId\":\"InternalAccount:019542f5-b3e7-1d02-0000-000000000002\",\"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" } @@ -641,7 +641,7 @@ A credential is revoked by signing with a session from **a different credential ```json { "type": "PASSKEY", - "payloadToSign": "Y2hhbGxlbmdlLXBheWxvYWQtdG8tc2lnbg==", + "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" } diff --git a/mintlify/snippets/global-accounts/exporting-wallet.mdx b/mintlify/snippets/global-accounts/exporting-wallet.mdx index f59aa3e3..7d2ec7a2 100644 --- a/mintlify/snippets/global-accounts/exporting-wallet.mdx +++ b/mintlify/snippets/global-accounts/exporting-wallet.mdx @@ -36,7 +36,7 @@ sequenceDiagram ```json { - "payloadToSign": "Y2hhbGxlbmdlLXBheWxvYWQtdG8tc2lnbg==", + "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" } diff --git a/mintlify/snippets/global-accounts/managing-sessions.mdx b/mintlify/snippets/global-accounts/managing-sessions.mdx index 8974f70d..81f16c1f 100644 --- a/mintlify/snippets/global-accounts/managing-sessions.mdx +++ b/mintlify/snippets/global-accounts/managing-sessions.mdx @@ -52,7 +52,7 @@ Session revocation uses the same ` identifier for this pending request. Echo this value exactly in the `Request-Id` header on the signed retry so the server can correlate the retry with the issued challenge. diff --git a/openapi/components/schemas/common/SignedRequestChallenge.yaml b/openapi/components/schemas/common/SignedRequestChallenge.yaml index f63bc2cf..0c279d28 100644 --- 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 index b1f0714c..b0ccb07f 100644 --- 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 index 03f8e516..5fe3be40 100644 --- 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 index a15f36b0..623189d9 100644 --- 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':