Call a capability

Authenticate

The gateway accepts three credential types, in priority order:

1. API key — Authorization: Bearer lip_live_... (most agent-to-server use)
2. OAuth 2.1 access token — Authorization: Bearer <jwt> (third-party connected apps)
3. Dashboard session cookie — Cookie: lipafy_session=... (only when calling from the dashboard frontend)

See Authentication for which to use when.

Resolve capability + check status

Lipafy looks up the slug. If it’s draft or disabled, the request fails with 422 capability_disabled. If the slug doesn’t exist at all → 404 capability_not_found.

Run spending controls

The grant attached to your credential (API key grants, OAuth grants, or your account_default grant for direct sign-in) carries spending controls:

• Daily cap
• Per-transaction cap
• Allow / block lists on slugs
• Escalation threshold (requires human approval above N KES)

Any cap exceeded → 402 with a code: daily_limit_exceeded, transaction_limit_exceeded, capability_blocked, capability_not_allowed. See Grants and controls.

Maybe pause for human approval

If the call is above your escalation threshold, the gateway responds with:

1
HTTP/1.1 402 Payment Required
2
Content-Type: application/json
3
4
{
5
  "error": "approval_required",
6
  "message": "Human approval required before this call can proceed",
7
  "details": {
8
    "approval_id": "uuid",
9
    "amount": "5000",
10
    "currency_code": "KES"
11
  }
12
}

Your client should pause, present the pending approval to the human (via your UI, the Lipafy dashboard at /approvals, or an SSE listener on /v1/notifications), and retry the same request once the approval is granted. The approval_id is consumed atomically on the next call — exactly-once. See Approvals.

Hold price from wallet

Lipafy debits the price (e.g. 500 KES) from your wallet’s available balance and writes it to held_balance. If available < price → 402 insufficient_balance. The hold is reversible right up until step 7.

Forward to upstream

Lipafy issues the upstream call:

• Method: same as yours.
• Path: everything after /gateway/<slug>/ is appended to the capability’s endpoint_url.
• Headers: yours pass through, except Authorization, X-Payment-Authorization, Cookie, and hop-by-hop headers are stripped. The capability’s configured auth (bearer / api_key / basic / none) is injected.
• Body: byte-for-byte.

Settle the hold

• Upstream returned 2xx → confirm the hold (your wallet’s held_balance → debit, provider’s wallet credit minus revenue share), write a signed receipt to capability_requests.
• Upstream returned 4xx or 5xx → release the hold (held → available, no charge), no receipt.

Either way, the upstream’s response — status code, headers, body — is what you receive, augmented with payment headers.