diff --git a/mintlify/docs.json b/mintlify/docs.json index 37e8d76d..d3280b5d 100644 --- a/mintlify/docs.json +++ b/mintlify/docs.json @@ -91,6 +91,14 @@ "global-accounts/exporting-wallet" ] }, + { + "group": "Agents (experimental)", + "pages": [ + "global-accounts/agents/overview", + "global-accounts/agents/policies-and-permissions", + "global-accounts/agents/approvals-and-audit" + ] + }, { "group": "Platform tools", "pages": [ diff --git a/mintlify/global-accounts/agents/approvals-and-audit.mdx b/mintlify/global-accounts/agents/approvals-and-audit.mdx new file mode 100644 index 00000000..d3765d9d --- /dev/null +++ b/mintlify/global-accounts/agents/approvals-and-audit.mdx @@ -0,0 +1,126 @@ +--- +title: "Approvals & audit" +description: "Design approval, activity, and revoke experiences for agent-driven Global Account flows" +icon: "/images/icons/receipt-check.svg" +"og:image": "/images/og/og-global-accounts.webp" +--- + + +Agent connectivity is currently limited availability. To request access, [book a demo](https://www.lightspark.com/contact) or reach out to your Lightspark contact. + + +Use this page to design how permission requests, decisions, and agent history appear in your app or dashboard. The connected agent may run outside both Grid and your product, but Grid owns approval state, execution gating, and audit history while your surfaces present those requests and records to the user. + + +Treat approval requests like first-class user tasks. They should be easy to find, easy to understand, and safe to retry without duplicating execution. + + +## Approval lifecycle + +When an agent requests an action that is not eligible for automatic execution: + +1. Grid creates a permission request for your product. +2. Grid dispatches that request to your product, typically via webhook or another configured callback mechanism. +3. Your app or dashboard shows the user the requested amount, source account, destination, and reason. +4. The user approves or rejects the action from that trusted surface. +5. Grid executes or rejects the action based on the latest account and policy state. +6. Grid records the final status and links it to the resulting transaction or quote execution. + +## Approval outcomes + +An approval request shown to the user is still subject to the latest account and policy state when Grid processes the decision. + +For example, between the original request and the final decision: + +- The agent may have been paused +- The customer's limits may have been reduced +- The permitted accounts may have changed +- Another action may already have consumed the available daily spend + + +An approval in your UI is not always a guarantee that the original request will execute successfully. Your product should be ready to show a final rejected or failed state if the request is no longer valid when Grid processes it. + + +## Activity and audit records + +The activity and audit data returned by Grid makes it easy for customers and operators to understand both intent and outcome. + +Each activity record captures: + +- Agent ID and display name +- Action type +- Requested amount and asset +- Source and destination context +- Reason or natural-language detail +- Policy decision +- Approval status +- Linked Grid quote ID or transaction ID, when available +- Created, approved, rejected, and completed timestamps + +For example, a permission request surfaced in your product might look like: + +```json +{ + "id": "Approval:019542f5-b3e7-1d02-0000-000000000099", + "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042", + "status": "PENDING", + "actionType": "EXECUTE_QUOTE", + "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000025", + "source": { + "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965", + "currency": "USD" + }, + "destination": { + "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123", + "currency": "EUR" + }, + "sendingAmount": { + "amount": 50000, + "currency": { + "code": "USD", + "decimals": 2 + } + }, + "description": "Send supplier payout", + "policyDecision": "APPROVAL_REQUIRED", + "createdAt": "2025-10-03T15:00:00Z" +} +``` + +This lets you present a clean customer-facing activity feed while preserving an operator-friendly audit trail. + +## Pause and revoke + +Customers need immediate control over delegated access. + +Support at least two controls: + +- `Pause`: temporarily block new executions while preserving the agent configuration. +- `Revoke`: permanently remove delegated access and invalidate the agent connection. + +Pause is useful for temporary uncertainty. Revoke is appropriate when a device is lost, a credential is exposed, or the customer no longer wants the agent connected. + +Grid enforces these controls. Your product should surface the current connection state and expose the relevant actions in your own experience. + +## What to show in the approval UI + +Your approval UI should answer: + +- What is the agent trying to do? +- Which account is affected? +- How much value is moving? +- Who or what is on the other side of the transaction? +- Why is approval required? + +If the user cannot answer those questions quickly, the approval surface is too opaque. + +## Integration guidance + +- Use Grid events or webhooks to reconcile approval decisions with the final activity and transaction state. +- Treat approval decisions as idempotent in your integration so duplicate taps or retries do not create a confusing UX. +- Preserve status history in your UI instead of collapsing everything into a single final state. +- Make agent connection status, approval queue state, and audit history easy to surface in your apps and dashboards. + + +Show approvals and audit history close to the account or transaction views users already trust. That reduces confusion and makes agent activity feel like part of the main account lifecycle rather than a separate subsystem. + diff --git a/mintlify/global-accounts/agents/overview.mdx b/mintlify/global-accounts/agents/overview.mdx new file mode 100644 index 00000000..39e606a4 --- /dev/null +++ b/mintlify/global-accounts/agents/overview.mdx @@ -0,0 +1,110 @@ +--- +title: "Overview" +description: "Experimental native Grid functionality for connecting AI agents to Global Accounts with managed policy and approval flows" +icon: "/images/icons/agent.svg" +"og:image": "/images/og/og-global-accounts.webp" +--- + +import { FeatureCard, FeatureCardGrid } from '/snippets/feature-card.mdx'; + + +This section describes experimental Grid functionality. Details may evolve as the agent product surface expands. Agent connectivity is currently limited availability. To request access, [book a demo](https://www.lightspark.com/contact) or reach out to your Lightspark contact. + + +Use Grid-managed agent connectivity to let your users connect AI agents to Global Accounts. The connected agent may run in your product, on the user's device, or through a third-party tool such as OpenClaw or Codex. Grid does not run the agent runtime. Grid powers install, delegated credentials, policy evaluation, approval state, and execution boundaries for agent-initiated actions, while your product surfaces the connection, approval, and history experience to the end user. + + + +## Design principles + + + + Delegation does not transfer account ownership. The customer can still require approvals, pause access, or revoke the agent entirely. + + + Permissions, spend limits, account restrictions, and approval thresholds are evaluated by Grid before any agent-initiated action executes. + + + Agents operate with a narrow, explicit capability set such as viewing balances, preparing withdrawals, or initiating transfers under Grid-defined controls. + + + Every agent-initiated action stays traceable through Grid policy decisions, approval state, and final settlement outcomes. + + + +## How it works + +In this model: + +- The customer still owns the Global Account and remains the ultimate authority over outbound movement. +- You let users connect one or more AI agents they already use to their Grid-backed account experience. +- The connected agent may run in your app, on the user's device, or through a third-party tool. +- Grid powers agent install and delegated credentials for the connected agent. +- Grid manages the agent's allowed capabilities, evaluation rules, and approval requirements. +- The agent can propose or execute only the actions Grid allows for that customer and account scope. +- Your surfaces remain the place where users view connection status, review permission requests, and inspect agent history. + +## System flow + +```mermaid +sequenceDiagram + participant U as User + participant P as Partner app + participant G as Grid + participant A as Connected agent + + U->>P: Connect agent + P->>G: Start Grid-powered install flow + G-->>P: Agent connection + delegated credentials + A->>G: Request action + Note over G,P: If approval is required + G-->>P: Permission request + P-->>U: Show approval UI + U->>P: Approve or reject + P->>G: Send decision + G-->>P: Action executed automatically or after approval + G-->>P: Activity, transaction, and audit updates +``` + +## Typical flow + +1. Your platform creates or links a Global Account for the customer. +2. The customer connects an existing agent through a Grid-powered install flow embedded in your product. +3. Grid creates the agent connection, provisions delegated credentials, and saves the configured policy. +4. The agent requests an action such as creating a quote, creating an external account, or executing a withdrawal. +5. Grid applies the saved policy for that connection. +6. The request is either denied, executed automatically, or delivered to your product as a permission request. +7. Your user reviews the request in a trusted surface you control. +8. Grid then sends the resulting activity, transaction, and settlement updates back to your product. + +## Where Global Accounts fits + +This functionality is a natural extension of Global Accounts because outbound money movement already assumes customer-level authorization. Agent access adds a delegated actor while preserving the user's ownership and approval model. + +## What you surface + +Your product should surface: + +- Agent connection state and metadata +- Policy configuration and permissions screens +- Approval and decision UX presented to end users on demand +- Agent activity, audit records, and transaction history +- Consumption of Grid events, webhooks, or approval callbacks +- Customer messaging and notification design + +## Next steps + + + + Define what a connected agent can do, which accounts it can access, and when Grid requires approval. + + + Design the approval and history experience your users see in your app or dashboard. + + diff --git a/mintlify/global-accounts/agents/policies-and-permissions.mdx b/mintlify/global-accounts/agents/policies-and-permissions.mdx new file mode 100644 index 00000000..ff9d643a --- /dev/null +++ b/mintlify/global-accounts/agents/policies-and-permissions.mdx @@ -0,0 +1,153 @@ +--- +title: "Policies & permissions" +description: "Define bounded agent access for Global Accounts with permissions, limits, restrictions, and approval thresholds" +icon: "/images/icons/shield.svg" +"og:image": "/images/og/og-global-accounts.webp" +--- + + +Agent connectivity is currently limited availability. To request access, [book a demo](https://www.lightspark.com/contact) or reach out to your Lightspark contact. + + + +Grid evaluates and enforces agent policy. Your product should let users review and update that policy, then reflect the resulting approval behavior in the UI. + + +Grid attaches policy to the Grid-managed agent connection, so your product does not need to implement a separate delegated credential model. + +That policy applies to the connected agent regardless of whether it runs in your app, on the user's device, or through a third-party tool. + +Use this page to decide how much authority to give a connected agent and when that authority should stop and ask the user. + + +Your app or dashboard should also surface the policy configuration screen itself so users can review and update permissions, limits, and approval behavior without leaving your product. + + +An agent policy should answer four questions: + +1. What actions may this agent take? +2. Which accounts may it act on? +3. How much value may it move? +4. When must Grid request user approval through your product? + +## Permissions + +Grid exposes explicit allowlists instead of broad agent access. Common permissions include: + +- View balances and account details +- View transaction history +- Create external accounts +- Create quotes +- Execute withdrawals or quote-backed transfers +- Fund or move value between allowed accounts + +These permissions are intentionally narrow and map to concrete Grid-backed actions rather than broad scopes such as "manage wallet." + +## Account restrictions + +If a customer has multiple internal accounts, an agent should not automatically access all of them. + +Use account restrictions to define: + +- Which internal account IDs are in scope +- Whether some accounts are view-only +- Whether some accounts require stricter execution rules than others + +This is especially useful when a customer has separate balances for treasury, payroll, or operational use cases and only one pool should be agent-accessible. + +## Spending limits + +Use value-based limits to contain damage if the agent behaves unexpectedly or the agent connection is misused. + +Common controls: + +- Per-transaction limit +- Daily spend limit +- Monthly spend limit +- Daily transaction count limit + +Keep limits in the smallest currency unit used by Grid so comparisons are exact and auditable. + +## Execution modes + +Each action should resolve to one of two execution modes: + +- `auto`: Grid may execute the action immediately after policy validation. +- `approval_required`: Grid creates a pending approval and dispatches it to your product for customer confirmation. + +You can apply execution mode globally or per account. A practical pattern is to allow automatic execution for low-risk actions and require approvals for higher-value withdrawals or new destination setup. + +## Approval thresholds + +Approval thresholds let Grid mix automation with customer oversight. + +Examples: + +- Auto-execute transfers below a configured amount +- Require approval above that amount +- Always require approval when the destination is new +- Always require approval for specific action types, regardless of amount + +Thresholds should complement permissions and limits, not replace them. + +## Example policy shape + +At a minimum, the policy configuration for a connection should include: + +- Allowed permissions +- Default execution mode +- Spending limits +- Allowed account IDs +- Per-account overrides +- Approval thresholds + +For example, Grid stores and enforces a policy object shaped like: + +```json +{ + "permissions": [ + "view_balances", + "view_transactions", + "create_external_accounts", + "execute_withdrawals" + ], + "defaultExecutionMode": "approval_required", + "spendingLimits": { + "perTransaction": { + "amount": 50000, + "currency": "USD" + }, + "daily": { + "amount": 200000, + "currency": "USD" + }, + "dailyTransactionCount": 5 + }, + "accountRestrictions": { + "allowedAccountIds": [ + "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965" + ] + }, + "approvalThresholds": { + "amount": 25000, + "currency": "USD" + } +} +``` + + +Policy amounts use the smallest unit of the specified currency. For example, `50000` with `"currency": "USD"` means $500.00. If Grid compares across currencies or assets, it uses the current exchange rate at evaluation time. + + +## Practical guidance + +- Default new agents to the smallest possible permission set. +- Separate read permissions from money movement permissions. +- Require approval for destination creation until you trust your identity, sanctions, and beneficiary review flow. +- Make the current policy visible to the customer in your app or dashboard. + +## Next steps + +- [Global Accounts overview](/global-accounts) +- [Implementation overview](/global-accounts/implementation-overview) +- [Approvals & audit](/global-accounts/agents/approvals-and-audit) diff --git a/mintlify/global-accounts/index.mdx b/mintlify/global-accounts/index.mdx index 5c8b6c3f..2e4cca94 100644 --- a/mintlify/global-accounts/index.mdx +++ b/mintlify/global-accounts/index.mdx @@ -63,6 +63,9 @@ Some Global Accounts capabilities require platform enablement before you can bui End-to-end walkthrough: create a customer, register a passkey, fund the account, and execute a signed withdrawal. + + Native Grid support for connected AI agents, managed permissions, and partner approval surfaces. + Passkey, OAuth (OIDC), and email OTP registration and reauthentication flows.