Skip to main content

​
Policies

Policies are reusable templates that define spending controls. Instead of configuring limits on each card, create a policy once and apply it to multiple agents or cards.

​
Why Policies?

Without PoliciesWith Policies
Configure limits on each cardDefine once, reuse everywhere
Update each card individuallyUpdate policy, all cards inherit
Inconsistent configurationsStandardized spending rules

​
Create a Policy

curl -X POST https://api.ledger.so/v1/policies \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "standard-agent",
    "description": "Standard spending limits for agents",
    "limitPerAuth": 10000,
    "limitPerDay": 50000,
    "limitPerMonth": 200000,
    "cooldownMinutes": 5,
    "requireAttestation": true
  }'

{
  "object": "policy",
  "id": "pol_abc123",
  "name": "standard-agent",
  "description": "Standard spending limits for agents",
  "limitPerAuth": 10000,
  "limitPerDay": 50000,
  "limitPerMonth": 200000,
  "cooldownMinutes": 5,
  "requireAttestation": true,
  "createdAt": 1703520000000
}

​
Policy Fields

​
Spending Limits

FieldDescription
limitPerAuthMax per transaction (cents)
limitPerDayMax per 24 hours (cents)
limitPerMonthMax per calendar month (cents)
cumulativeMaxLifetime max spending (cents)
maxAuthCountMax number of transactions

​
Time Controls

FieldDescription
ttlMinutesCard auto-expires after N minutes
onExpiryAction on expiry: freeze or close
activeHoursStartHour (0-23) when card activates
activeHoursEndHour (0-23) when card deactivates
activeTimezoneIANA timezone (e.g., “America/New_York”)
activeDaysDays of week (0=Sun through 6=Sat)
cooldownMinutesMin time between transactions

​
Attestation

FieldDescription
requireAttestationMust declare intent before use
intentToleranceMax % variance from declared amount (0.0-1.0)
merchantHintExpected merchant name
onDriftAction on merchant mismatch: allow, flag, decline

​
List Policies

curl https://api.ledger.so/v1/policies \
  -H "Api-Key: $API_KEY"

{
  "object": "list",
  "data": [
    {
      "object": "policy",
      "id": "pol_abc123",
      "name": "standard-agent",
      "description": "Standard spending limits for agents",
      "limitPerAuth": 10000,
      "createdAt": 1703520000000
    },
    {
      "object": "policy",
      "id": "pol_def456",
      "name": "high-value",
      "description": "For high-value purchases",
      "limitPerAuth": 100000,
      "createdAt": 1703520000000
    }
  ],
  "hasMore": false
}

​
Get Policy

curl https://api.ledger.so/v1/policies/pol_abc123 \
  -H "Api-Key: $API_KEY"

​
Update Policy

curl -X PATCH https://api.ledger.so/v1/policies/pol_abc123 \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "limitPerAuth": 15000,
    "description": "Updated standard limits"
  }'
Updating a policy affects all agents and cards using it. Changes take effect immediately.

​
Delete Policy

curl -X DELETE https://api.ledger.so/v1/policies/pol_abc123 \
  -H "Api-Key: $API_KEY"
You cannot delete a policy that’s in use by agents or cards.

​
Using Policies

​
Assign to Agent

When creating an agent, specify a default policy: 
curl -X POST https://api.ledger.so/v1/agents \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "name": "shopping-agent",
    "defaultPolicyId": "pol_abc123"
  }'
All cards created for this agent will inherit the policy.

​
Assign to Card

Override the agent’s policy for a specific card: 
curl -X POST https://api.ledger.so/v1/agents/agent_xyz/cards \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "Special purchase",
    "type": "single",
    "policyId": "pol_def456"
  }'

​
Policy Inheritance

Policy Template
    └── Agent (defaultPolicyId)
          └── Card (inherits or overrides)
  • Cards inherit from their agent’s defaultPolicyId
  • Cards can override with their own policyId
  • Inline policy fields on card creation override template values

​
Example Policies

​
Business Hours Only

{
  "name": "business-hours",
  "activeHoursStart": 9,
  "activeHoursEnd": 17,
  "activeTimezone": "America/New_York",
  "activeDays": [1, 2, 3, 4, 5],
  "limitPerDay": 50000
}

​
High-Security

{
  "name": "high-security",
  "limitPerAuth": 5000,
  "cooldownMinutes": 10,
  "requireAttestation": true,
  "intentTolerance": 0.05,
  "maxAuthCount": 5
}

​
Subscription Card

{
  "name": "subscription",
  "limitPerMonth": 10000,
  "merchantHint": "Netflix",
  "onDrift": "decline"
}

Cards

Learn about card policies in detail