Update agent policy

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/policy \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "permissions": [],
  "spendingLimits": {
    "currency": "USD",
    "perTransactionLimit": 50000,
    "dailyLimit": 500000,
    "dailyTransactionLimit": 10,
    "monthlyLimit": 5000000
  },
  "accountRestrictions": {
    "allowedAccountIds": [
      "Account:019542f5-b3e7-1d02-0000-000000000001"
    ],
    "accountRules": [
      {
        "accountId": "Account:019542f5-b3e7-1d02-0000-000000000001",
        "perTransactionLimit": 10000
      }
    ]
  },
  "approvalThresholds": {
    "currency": "USD",
    "amount": 100000
  }
}
'

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    permissions: [],
    spendingLimits: {
      currency: 'USD',
      perTransactionLimit: 50000,
      dailyLimit: 500000,
      dailyTransactionLimit: 10,
      monthlyLimit: 5000000
    },
    accountRestrictions: {
      allowedAccountIds: ['Account:019542f5-b3e7-1d02-0000-000000000001'],
      accountRules: [
        {
          accountId: 'Account:019542f5-b3e7-1d02-0000-000000000001',
          perTransactionLimit: 10000
        }
      ]
    },
    approvalThresholds: {currency: 'USD', amount: 100000}
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/policy', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"permissions\": [],\n  \"spendingLimits\": {\n    \"currency\": \"USD\",\n    \"perTransactionLimit\": 50000,\n    \"dailyLimit\": 500000,\n    \"dailyTransactionLimit\": 10,\n    \"monthlyLimit\": 5000000\n  },\n  \"accountRestrictions\": {\n    \"allowedAccountIds\": [\n      \"Account:019542f5-b3e7-1d02-0000-000000000001\"\n    ],\n    \"accountRules\": [\n      {\n        \"accountId\": \"Account:019542f5-b3e7-1d02-0000-000000000001\",\n        \"perTransactionLimit\": 10000\n      }\n    ]\n  },\n  \"approvalThresholds\": {\n    \"currency\": \"USD\",\n    \"amount\": 100000\n  }\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/policy")
  .patch(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "id": "Agent:019542f5-b3e7-1d02-0000-000000000001",
  "name": "Payroll Automation Agent",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "isPaused": false,
  "isConnected": true,
  "policy": {
    "permissions": [
      "VIEW_TRANSACTIONS"
    ],
    "defaultExecutionMode": "AUTO",
    "spendingLimits": {
      "currency": "USD",
      "perTransactionLimit": 50000,
      "dailyLimit": 500000,
      "dailyTransactionLimit": 10,
      "monthlyLimit": 5000000
    },
    "accountRestrictions": {
      "allowedAccountIds": [
        "Account:019542f5-b3e7-1d02-0000-000000000001"
      ],
      "accountRules": [
        {
          "accountId": "Account:019542f5-b3e7-1d02-0000-000000000001",
          "executionMode": "AUTO",
          "perTransactionLimit": 10000
        }
      ]
    },
    "approvalThresholds": {
      "currency": "USD",
      "amount": 100000
    }
  },
  "usage": {
    "dailyTransactionCount": 3,
    "dailySpend": 150000,
    "monthlySpend": 750000,
    "dailyResetDate": "2025-07-22",
    "monthlyResetMonth": "2025-08"
  },
  "createdAt": "2025-07-21T17:32:28Z",
  "updatedAt": "2025-07-21T17:32:28Z",
  "actingFor": "member_8f2c1a",
  "spendingPoolId": "SpendingPool:019542f5-b3e7-1d02-0000-000000000007"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

PATCH

agents

{agentId}

policy

Update agent policy

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/policy \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "permissions": [],
  "spendingLimits": {
    "currency": "USD",
    "perTransactionLimit": 50000,
    "dailyLimit": 500000,
    "dailyTransactionLimit": 10,
    "monthlyLimit": 5000000
  },
  "accountRestrictions": {
    "allowedAccountIds": [
      "Account:019542f5-b3e7-1d02-0000-000000000001"
    ],
    "accountRules": [
      {
        "accountId": "Account:019542f5-b3e7-1d02-0000-000000000001",
        "perTransactionLimit": 10000
      }
    ]
  },
  "approvalThresholds": {
    "currency": "USD",
    "amount": 100000
  }
}
'

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    permissions: [],
    spendingLimits: {
      currency: 'USD',
      perTransactionLimit: 50000,
      dailyLimit: 500000,
      dailyTransactionLimit: 10,
      monthlyLimit: 5000000
    },
    accountRestrictions: {
      allowedAccountIds: ['Account:019542f5-b3e7-1d02-0000-000000000001'],
      accountRules: [
        {
          accountId: 'Account:019542f5-b3e7-1d02-0000-000000000001',
          perTransactionLimit: 10000
        }
      ]
    },
    approvalThresholds: {currency: 'USD', amount: 100000}
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/policy', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"permissions\": [],\n  \"spendingLimits\": {\n    \"currency\": \"USD\",\n    \"perTransactionLimit\": 50000,\n    \"dailyLimit\": 500000,\n    \"dailyTransactionLimit\": 10,\n    \"monthlyLimit\": 5000000\n  },\n  \"accountRestrictions\": {\n    \"allowedAccountIds\": [\n      \"Account:019542f5-b3e7-1d02-0000-000000000001\"\n    ],\n    \"accountRules\": [\n      {\n        \"accountId\": \"Account:019542f5-b3e7-1d02-0000-000000000001\",\n        \"perTransactionLimit\": 10000\n      }\n    ]\n  },\n  \"approvalThresholds\": {\n    \"currency\": \"USD\",\n    \"amount\": 100000\n  }\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/policy")
  .patch(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "id": "Agent:019542f5-b3e7-1d02-0000-000000000001",
  "name": "Payroll Automation Agent",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "isPaused": false,
  "isConnected": true,
  "policy": {
    "permissions": [
      "VIEW_TRANSACTIONS"
    ],
    "defaultExecutionMode": "AUTO",
    "spendingLimits": {
      "currency": "USD",
      "perTransactionLimit": 50000,
      "dailyLimit": 500000,
      "dailyTransactionLimit": 10,
      "monthlyLimit": 5000000
    },
    "accountRestrictions": {
      "allowedAccountIds": [
        "Account:019542f5-b3e7-1d02-0000-000000000001"
      ],
      "accountRules": [
        {
          "accountId": "Account:019542f5-b3e7-1d02-0000-000000000001",
          "executionMode": "AUTO",
          "perTransactionLimit": 10000
        }
      ]
    },
    "approvalThresholds": {
      "currency": "USD",
      "amount": 100000
    }
  },
  "usage": {
    "dailyTransactionCount": 3,
    "dailySpend": 150000,
    "monthlySpend": 750000,
    "dailyResetDate": "2025-07-22",
    "monthlyResetMonth": "2025-08"
  },
  "createdAt": "2025-07-21T17:32:28Z",
  "updatedAt": "2025-07-21T17:32:28Z",
  "actingFor": "member_8f2c1a",
  "spendingPoolId": "SpendingPool:019542f5-b3e7-1d02-0000-000000000007"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

API token authentication using format <api token id>:<api client secret>

Path Parameters

agentId

string

required

System-generated unique agent identifier

Body

application/json

Partial update to an agent's policy. Only provided fields will be updated; omitted fields retain their current values.

permissions

enum<string>[]

Updated list of permissions. Replaces the entire permissions list when provided.

Permission granted to an agent that determines what actions it can perform. VIEW_TRANSACTIONS: Can list and retrieve transactions and account balances. CREATE_QUOTES: Can create quotes. EXECUTE_QUOTES: Can execute quotes. MANAGE_EXTERNAL_ACCOUNTS: Can create and manage external accounts. RECEIVE_FUNDS: Can create deposit targets for receiving funds. MANAGE_IDENTITY: Can read and update customer identity information and start verification. MANAGE_CARDS: Can read, tighten, and freeze its cards. ISSUE_CARDS: Can issue one standard virtual card for itself while it holds no live standard card, and single-use and recurring purchase cards where the platform enables them. USE_STORED_CARDS: Can list the customer's stored cards it is allowed to use and ask for a single-use link to one's details. Never granted by default. MANAGE_SETTLEMENT_RULES: Can propose settlement rules that split the customer's incoming payments into its Embedded Wallet, read and delete the rules it created, and cancel their held executions.

Available options:

VIEW_TRANSACTIONS,

CREATE_QUOTES,

EXECUTE_QUOTES,

MANAGE_EXTERNAL_ACCOUNTS,

RECEIVE_FUNDS,

MANAGE_IDENTITY,

MANAGE_CARDS,

ISSUE_CARDS,

USE_STORED_CARDS,

MANAGE_SETTLEMENT_RULES

defaultExecutionMode

enum<string>

Execution mode controlling whether agent actions require human approval. AUTO: The agent can execute actions autonomously without explicit approval. APPROVAL_REQUIRED: All agent actions require explicit human approval before execution.

Available options:

AUTO,

APPROVAL_REQUIRED

spendingLimits

object

Partial update to spending limits. Only provided fields will be updated; omitted fields retain their current values.

Show child attributes

accountRestrictions

object

Optional restrictions that limit the agent to specific accounts or override policy per account.

Show child attributes

approvalThresholds

object

Thresholds that force approval for high-value transactions, overriding the default execution mode. The threshold currency must equal the policy's spending limits currency. When a transaction is denominated in a different currency, Grid converts it to the policy currency at evaluation time.

Show child attributes

Response

Agent policy updated successfully

A programmatic agent with scoped permissions and a spending policy, used to automate payment workflows.

string

required

System-generated unique identifier for the agent.

Example:

"Agent:019542f5-b3e7-1d02-0000-000000000001"

name

string

required

Human-readable name for the agent.

Example:

"Payroll Automation Agent"

customerId

string

required

The ID of the customer this agent operates on behalf of.

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

isPaused

boolean

required

Whether the agent is currently paused. Paused agents cannot initiate any actions.

Example:

false

isConnected

boolean

required

Whether the agent has been installed and connected (i.e., its device code has been redeemed).

Example:

true

policy

object

required

Policy governing what an agent can do, how it executes actions, and its spending boundaries.

Show child attributes

usage

object

required

Real-time counters tracking the agent's spending and transaction activity against its policy limits.

Show child attributes

createdAt

string<date-time>

required

Creation timestamp.

Example:

"2025-07-21T17:32:28Z"

updatedAt

string<date-time>

required

Last update timestamp.

Example:

"2025-07-21T17:32:28Z"

actingFor

string

The platform's reference for the person this agent acts for, as given when the agent was created. Absent when none was given.

Example:

"member_8f2c1a"

spendingPoolId

string

The spending pool the agent spends under, in addition to its own policy. Absent when the agent is in no pool.

Example:

"SpendingPool:019542f5-b3e7-1d02-0000-000000000007"

Using the API

API documentation

Update agent policy

Authorizations

Path Parameters

Body

Response