LimitLayer API — Developer Reference

1. Authentication

LimitLayer supports two authentication methods. Both can be used on every endpoint.

1a. API Key (recommended for machines)

Send the raw API key in either header:

X-API-Key: ll_aBcDeFgH...          ← preferred
Authorization: Bearer ll_aBcDeFgH... ← also accepted

1b. JWT Token (recommended for dashboard users)

External (tenant) login:

POST /auth/v2/login
Content-Type: application/json

{
  "email": "user@yourcompany.com",
  "password": "your-password"
}

Internal / admin login:

POST /auth/v2/admin/login
Content-Type: application/json

{
  "email": "admin@limitlayer.com",
  "password": "your-password"
}

Both return:

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 3600
}

Use the token in subsequent requests:

Authorization: Bearer eyJ...

Verify your identity

2. Roles & Permissions

Tenant Roles (per-organisation)

Platform Roles (internal staff only)

Endpoint Permission Matrix

3. Organisation & API Keys

Register your organisation to get started. The API key returned is shown once only — store it securely immediately.

4. Wallets

Wallets hold budget allocations. Every agent is attached to one wallet.

Budget field glossary

5. Agents

Agents are AI identities that make spending requests. Each agent belongs to one wallet.

6. Policies

Policies define rules the transaction engine enforces before approving any spend request. Set agent_id to scope to one agent, wallet_id for all agents in a wallet, or both.

Policy types

7. Transactions

The core flow: an agent requests a transaction → policies are evaluated → decision is returned.

CREATED → [REQUIRES_APPROVAL] → APPROVED → PAYMENT_CONFIRMED
                                          → PAYMENT_FAILED (wallet reversed)
         → DENIED
         → EXPIRED  (approval window elapsed)

List transactions — query parameters

8. Approvals

When a transaction requires human approval it enters a 24-hour approval window. If not resolved it transitions to EXPIRED.

9. Audit Log

Read-only transaction history for compliance and reporting.

Query parameters

10. Webhooks

Webhooks deliver real-time event notifications to your HTTP endpoint via signed POST requests.

Verifying webhook signatures

Every webhook POST includes an X-LimitLayer-Signature header. Verify it to ensure the payload is genuine.

import hmac, hashlib

def verify_signature(payload_bytes: bytes, header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", header)

const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

11. Webhook Event Payloads

All webhook POST bodies share this envelope:

{
  "event": "transaction.approved",
  "timestamp": "2026-03-28T10:00:00Z",
  "organisation_id": "uuid",
  "data": { }
}

Headers on every delivery:

X-LimitLayer-Signature: sha256=<hmac>
X-LimitLayer-Event: transaction.approved
Content-Type: application/json

{
  "transaction_id": "uuid",
  "agent_id": "uuid",
  "amount": 249.99,
  "currency": "USD",
  "merchant": "AWS",
  "wallet_remaining": 4750.01
}

{
  "transaction_id": "uuid",
  "agent_id": "uuid",
  "amount": 249.99,
  "currency": "USD",
  "merchant": "ShopXYZ",
  "denial_reason": "Merchant not in allowlist"
}

{
  "transaction_id": "uuid",
  "approval_id": "uuid",
  "agent_id": "uuid",
  "amount": 1500.00,
  "currency": "USD",
  "merchant": "Salesforce",
  "expires_at": "2026-03-29T10:00:00"
}

{
  "transaction_id": "uuid",
  "amount": 249.99,
  "currency": "USD",
  "merchant": "AWS",
  "payment_reference": "stripe_ch_abc123",
  "wallet_remaining": 4750.01
}

{
  "transaction_id": "uuid",
  "amount": 249.99,
  "currency": "USD",
  "merchant": "AWS",
  "payment_failure_reason": "Insufficient funds",
  "wallet_remaining": 5000.0
}

{
  "wallet_id": "uuid",
  "wallet_name": "GPT-4 Operations Budget",
  "budget": 5000.0,
  "total_approved": 3600.0,
  "remaining": 1400.0,
  "usage_pct": 72.0
}

{
  "wallet_id": "uuid",
  "wallet_name": "GPT-4 Operations Budget",
  "budget": 5000.0,
  "total_approved": 4600.0,
  "remaining": 400.0,
  "usage_pct": 92.0
}

12. Error Reference

All errors follow this shape: { "detail": "Human-readable error message" }

Common 401 causes

• API key not in X-API-Key header or Authorization: Bearer header
• API key is_active = false or status = revoked
• API key expires_at in the past
• JWT token expired or signature invalid

Common 403 causes

• Tenant role insufficient for this operation (see permission matrix)
• Cross-tenant request blocked (path org_id ≠ caller's org_id)
• Organisation inactive or soft-deleted

Last updated: March 2026