Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .stainless/stainless.yml
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,8 @@ resources:
business_info: "#/components/schemas/BusinessInfo"
internal_account_export_request: '#/components/schemas/InternalAccountExportRequest'
internal_account_export_response: '#/components/schemas/InternalAccountExportResponse'
internal_account_wallet_privacy_update_request: '#/components/schemas/InternalAccountWalletPrivacyUpdateRequest'
internal_account_wallet_privacy_update_response: '#/components/schemas/InternalAccountWalletPrivacyUpdateResponse'
methods:
create:
endpoint: post /customers
Expand All @@ -104,6 +106,9 @@ resources:
get_kyc_link: get /customers/kyc-link
list_internal_accounts: get /customers/internal-accounts
export: post /internal-accounts/{id}/export
update_wallet_privacy:
endpoint: patch /internal-accounts/{id}/wallet-privacy
body_param_name: InternalAccountWalletPrivacyUpdateRequest
# Subresources define resources that are nested within another for more powerful
# logical groupings, e.g. `cards.payments`.
subresources:
Expand Down
132 changes: 132 additions & 0 deletions mintlify/openapi.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion mintlify/snippets/global-accounts/authentication.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -540,7 +540,7 @@ The response is not paginated — each account holds a small, bounded number of

### The signed-retry pattern

Adding an additional credential, revoking a credential, revoking a session, and exporting a wallet all share the same shape:
Adding an additional credential, revoking a credential, revoking a session, exporting a wallet, and updating wallet privacy all share the same shape:

```mermaid
sequenceDiagram
Expand Down
2 changes: 1 addition & 1 deletion mintlify/snippets/global-accounts/client-keys.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -224,7 +224,7 @@ Grid returns `payloadToSign` strings from several endpoints:

- `POST /quotes` (when the source is a Global Account) — the quote's `paymentInstructions[].accountOrWalletInfo.payloadToSign`.
- `POST /auth/credentials` (adding an additional credential) — 202 response body.
- `DELETE /auth/credentials/{id}`, `DELETE /auth/sessions/{id}`, `POST /internal-accounts/{id}/export` — all 202 response bodies.
- `DELETE /auth/credentials/{id}`, `DELETE /auth/sessions/{id}`, `POST /internal-accounts/{id}/export`, `PATCH /internal-accounts/{id}/wallet-privacy` — all 202 response bodies.

Sign the payload **byte-for-byte as returned** (do not re-parse, re-serialize, or trim whitespace). The signature is ECDSA over SHA-256 using the session signing key, DER-encoded, then base64-encoded. Pass it as the `Grid-Wallet-Signature` header on the retry (and, for endpoints that use it, the `Request-Id` header echoed back from the 202).

Expand Down
6 changes: 3 additions & 3 deletions mintlify/snippets/global-accounts/concepts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,12 @@ The client **never** talks to Grid directly. Every request flows client → inte

## Auth credentials, client keys, and session signing keys

Three distinct pieces of crypto collaborate to authorize actions on the Global Account (withdrawals, credential changes, session revocations, and wallet exports):
Three distinct pieces of crypto collaborate to authorize actions on the Global Account (withdrawals, credential changes, session revocations, wallet exports, and wallet privacy updates):

| Piece | Where it lives | How long it lives | What it proves |
|---|---|---|---|
| **Auth credential** — passkey, OIDC token, or email OTP | Registered on the account; the passkey itself lives on the authenticator, OIDC on your IdP, OTP in the user's inbox | Until the customer revokes it | *"I am the human who owns this account."* Used to authenticate the user at the start of each session. |
| **Client key pair** (P-256) | Generated on the client device for each verification request; private key stays in device-local secure storage | One verification request | Binds a given session signing key delivery to the exact device that asked for it — Grid encrypts the session to this public key, so only this device can decrypt. |
| **Session signing key** (P-256) | Issued by Grid, sealed to the client public key, decrypted and held on the device for the session's lifetime | 15 minutes (default) | *"This specific account action was approved on an authenticated device."* Signs the `payloadToSign` Grid returns on quotes, credential changes, session revocations, and wallet exports. |
| **Session signing key** (P-256) | Issued by Grid, sealed to the client public key, decrypted and held on the device for the session's lifetime | 15 minutes (default) | *"This specific account action was approved on an authenticated device."* Signs the `payloadToSign` Grid returns on quotes, credential changes, session revocations, wallet exports, and wallet privacy updates. |

The flow is always the same: verify an auth credential → receive a short-lived session signing key → sign `payloadToSign` bytes on the client → pass the signature as the `Grid-Wallet-Signature` header on the request that actually moves funds or changes account state. This applies to withdrawals, adding or removing credentials, revoking sessions, and exporting the wallet seed.
The flow is always the same: verify an auth credential → receive a short-lived session signing key → sign `payloadToSign` bytes on the client → pass the signature as the `Grid-Wallet-Signature` header on the request that actually moves funds or changes account state. This applies to withdrawals, adding or removing credentials, revoking sessions, exporting the wallet seed, and updating wallet privacy.
1 change: 1 addition & 0 deletions mintlify/snippets/sandbox-global-account-magic.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,7 @@ Pass `sandbox-valid-signature` as the `Grid-Wallet-Signature` HTTP header on any
- `DELETE /auth/credentials/{id}` (revoke credential)
- `DELETE /auth/sessions/{id}` (revoke session)
- `POST /internal-accounts/{id}/export` (export wallet)
- `PATCH /internal-accounts/{id}/wallet-privacy` (update wallet privacy)
- `POST /quotes/{quoteId}/execute` (when source is an embedded wallet)

```bash
Expand Down
132 changes: 132 additions & 0 deletions openapi.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading