> ## Documentation Index
> Fetch the complete documentation index at: https://agents-docs.lightspark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents API integration

> For Grid platforms: create agents for your customers, connect their agent software, delegate signing, fund the account, and handle approvals from your backend.

> [!NOTE]
>
> The Agents API must be enabled for your platform; until it is, agent endpoints answer `403`. To enable it, [book a demo](https://www.lightspark.com/contact) or reach out to your Lightspark contact.

This guide is for Grid platforms adding agents for their own customers. If you build an AI app and want your users to get a Lightspark account inside it, see [AI app connector](https://agents-docs.lightspark.com/agent-accounts/ai-app-connector.md) instead.

This page walks the happy path from a verified customer to an agent that pays on its own under a limit and asks the customer above it. Each step links to the page that covers it in depth.

## Prerequisites

* The Agents API is enabled for your platform. Every agent endpoint answers `403` until it is.
* The customer exists and has completed KYC (or KYB for a business). In sandbox, customers are KYC-approved on creation.
* The customer has a [Global Account](https://agents-docs.lightspark.com/global-accounts.md) (an `EMBEDDED_WALLET` internal account), with a verified authentication credential you can use to sign. See [Implementation overview](https://agents-docs.lightspark.com/global-accounts/implementation-overview.md) for Global Accounts.

## Two kinds of credentials

| Caller | Authenticates with | Calls |
| - | - | - |
| **Your backend** | Your platform API token, HTTP Basic auth | `POST /agents`, `PATCH /agents/{agentId}/policy`, `POST /agents/{agentId}/actions/{actionId}/approve`, and every other platform endpoint |
| **The agent software** | The agent's access token, `Authorization: Bearer <accessToken>` | Endpoints under `/agents/me/...`, always scoped to the agent's customer and policy |

The agent never sees your platform credentials, and your backend never needs the agent's token.

## Sequence

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant P as Your backend
    participant G as Grid
    participant A as Agent software

    P->>G: POST /agents (customer, policy)
    G-->>P: Agent + one-time device code
    P-->>C: Show device code
    C->>A: Enter device code
    A->>G: POST /agents/device-codes/redeem
    G-->>A: Access token + policy
    C->>P: Authorize agent on the Global Account
    P->>G: POST /auth/delegated-keys (agentId, signed by customer)
    A->>G: POST /agents/me/quotes, then /execute
    alt Within policy
        G-->>A: AgentAction APPROVED + transaction
    else Needs approval
        G-->>A: AgentAction PENDING_APPROVAL
        G->>P: Webhook AGENT_ACTION.PENDING_APPROVAL
        P-->>C: Ask in your app
        C->>P: Approve
        P->>G: POST /agents/{agentId}/actions/{actionId}/approve
        G->>P: Webhook AGENT_ACTION.APPROVED
    end
    G->>P: OUTGOING_PAYMENT webhooks
```

## Walkthrough

**1. Create the agent**

Your backend creates the agent for a customer with a policy. Send an `Idempotency-Key` so a retry returns the same agent instead of creating a second one.

```bash theme={null}
curl -X POST "$GRID_BASE_URL/agents" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "name": "Shopping assistant",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "policy": {
      "permissions": ["VIEW_TRANSACTIONS", "CREATE_QUOTES", "EXECUTE_QUOTES", "RECEIVE_FUNDS"],
      "defaultExecutionMode": "AUTO",
      "spendingLimits": {
        "currency": "USD",
        "perTransactionLimit": 50000,
        "dailyLimit": 100000,
        "dailyTransactionLimit": 10
      },
      "approvalThresholds": { "currency": "USD", "amount": 2500 }
    }
  }'
```

The `201` response carries the `agent` and a `deviceCode`. See [Creating agents](https://agents-docs.lightspark.com/agent-accounts/creating-agents.md).

**2. Connect the agent software**

Show the customer the `deviceCode.code`. The agent software redeems it, without platform credentials, and receives its access token once:

```bash theme={null}
curl -X POST "$GRID_BASE_URL/agents/device-codes/redeem" \
  -H "Content-Type: application/json" \
  -d '{ "code": "jqzJR3AgI9OAwb_enypARw" }'
```

Poll `POST /agents/device-codes/status` from your backend to see when it is `REDEEMED`. The agent's `isConnected` becomes `true`.

**3. Let the agent sign from the Global Account**

The customer authorizes a delegated key for this agent and their Embedded Wallet with `POST /auth/delegated-keys` and `agentId`. Creation is a three-leg signed-retry flow signed with the customer's session key, so it always involves the customer. Without an `ACTIVE` key, the agent's quote executions from the wallet are refused. See [Creating agents](https://agents-docs.lightspark.com/agent-accounts/creating-agents.md#delegate-signing-on-the-global-account).

**4. Fund the account**

Fund the Global Account the way you fund any internal account, or let the agent create a deposit target with `POST /agents/me/deposits` (Lightning invoice or stablecoin address). In sandbox, use `POST /sandbox/internal-accounts/{accountId}/fund`. See [Funding](https://agents-docs.lightspark.com/agent-accounts/funding.md).

**5. The agent pays**

The agent quotes with `POST /agents/me/quotes` and executes with `POST /agents/me/quotes/{quoteId}/execute`. Execution returns an `AgentAction`: `APPROVED` with a `transaction` when the policy allows it, or `PENDING_APPROVAL` when the customer must decide. See [Payments](https://agents-docs.lightspark.com/agent-accounts/payments.md).

**6. Handle approvals**

Subscribe to `AGENT_ACTION.PENDING_APPROVAL`, show the customer the request, and call `POST /agents/{agentId}/actions/{actionId}/approve` or `.../reject` with their decision. The agent learns the outcome by polling `GET /agents/me/actions/{actionId}`. See [Approvals & audit](https://agents-docs.lightspark.com/agent-accounts/approvals-and-audit.md).

**7. Give the customer control**

Let the customer change the policy (`PATCH /agents/{agentId}/policy`), pause the agent (`PATCH /agents/{agentId}` with `isPaused: true`), or delete it (`DELETE /agents/{agentId}`). Paused agents cannot initiate any action; deleted agents lose access immediately.

## Where to next

> [card] [Policies & permissions](https://agents-docs.lightspark.com/agent-accounts/policies-and-permissions.md)
>
> Every policy field, and how Grid decides between executing, asking and refusing.

> [card] [Cards](https://agents-docs.lightspark.com/agent-accounts/cards.md)
>
> Purchase cards, recurring cards, and the customer's stored cards.

> [card] [Spending limits](https://agents-docs.lightspark.com/agent-accounts/spending-limits.md)
>
> Share one budget across a customer's agents with spending pools.

> [card] [Sandbox testing](https://agents-docs.lightspark.com/agent-accounts/platform-tools/sandbox-testing.md)
>
> Run the whole flow without moving real money.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.