From bd0067aa14b68b8e305471e22beae447d4f6a1ca Mon Sep 17 00:00:00 2001 From: Dhruv Pareek Date: Mon, 18 May 2026 17:02:53 -0700 Subject: [PATCH] docs: update auth signed retry examples Show Request: request IDs and canonical compact JSON payloadToSign examples for credential add/revoke, wallet export, and session revocation. Also fixes the export curl continuation while updating that snippet. --- mintlify/openapi.yaml | 12 ++++++------ .../snippets/global-accounts/authentication.mdx | 14 +++++++------- .../snippets/global-accounts/exporting-wallet.mdx | 8 ++++---- .../snippets/global-accounts/managing-sessions.mdx | 6 +++--- openapi.yaml | 12 ++++++------ .../schemas/common/SignedRequestChallenge.yaml | 2 +- openapi/paths/auth/auth_credentials.yaml | 6 +++--- .../paths/customers/customers_{customerId}.yaml | 2 +- .../internal_accounts/internal_accounts_{id}.yaml | 2 +- 9 files changed, 32 insertions(+), 32 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 6835912f..bdde8032 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -690,7 +690,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': @@ -3819,7 +3819,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': @@ -4040,21 +4040,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': @@ -8406,7 +8406,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 f34199e1..aee79c55 100644 --- 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:` 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 index 9624c18a..7d2ec7a2 100644 --- a/mintlify/snippets/global-accounts/exporting-wallet.mdx +++ b/mintlify/snippets/global-accounts/exporting-wallet.mdx @@ -25,7 +25,7 @@ sequenceDiagram ```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 index 4966b698..81f16c1f 100644 --- 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 ` 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':