Connections

Bounded grants and the delegations cut from them — who may act, on whose account, within what limits.

Requires a member credential. Every route on this page does.

A connection names a grantor, a grantee and a subject. It is read by those parties, and it is not served at /path/{reference}. The object model — consent, modes, mandates — is PATH CONNECT.

A capability that is absent is denied. There is no permissive default.

`POST /connect/connections`

Requires the local member credential. The caller is the grantor.

{
  "grantee": "member-b",
  "subject_id": "9f2c41a8-6d1e-4b07-9c3a-2e5f81d0a4b7",
  "capabilities": { "payment_request": true },
  "mode": "persistent_consent",
  "max_single": "100000",
  "max_total": "500000",
  "currency": "USD",
  "expires_at": "2027-01-01T00:00:00Z"
}

mode is per_operation_signature or persistent_consent. Pass a schedule and the object is a path.mandate: a permission that persists and recurs, rather than a one-off grant.

{
  "reference": "9kq3m7vx2pf8dn",
  "grantee": "member-b",
  "status": "active",
  "mode": "persistent_consent",
  "consent_digest": "8f29…",
  "expires_at": "2027-01-01T00:00:00Z"
}

The subject's consent is collected in the grantor's own product before this call. The signature on the resulting object attests that this operator collected that consent for these terms.

`GET /connect/connections/{reference}`

Requires a member credential. Either party.

The response is the signed connection. status and the counters are signed at read, because they move. consent is the envelope signed when the subject agreed, stored as it was. Read the terms from consent.

`POST /connect/connections/{reference}/consume`

Requires a member credential. The caller is the grantee.

{
  "capability": "payment_request",
  "amount": "5000",
  "currency": "USD",
  "operation_ref": "ledger-4412"
}

operation_ref is the caller's own handle, so its ledger and this log can be reconciled.

{
  "ok": true,
  "consumed_total": "125000",
  "consumed_operations": 7,
  "remaining_total": "375000"
}

Scope, currency and both ceilings are checked, and the counters move, in one locked statement. A refusal is path.connect.delegation_out_of_scope or path.connect.delegation_limit_reached.

`POST /connect/connections/{reference}/revoke`

Requires a member credential. Either party. The grantor withdraws; the grantee renounces. revoked_by records which.

{ "reason": "customer cancelled" }

{
  "reference": "9kq3m7vx2pf8dn",
  "status": "revoked",
  "revoked_at": "2026-09-09T10:14:22Z",
  "revoked_by": "member-a"
}

It takes effect at the next operation. The grantor reads the state live on every consume.

`GET /connect/connections/{reference}/usage`

Requires a member credential. Either party. Counters say how much; this says what and when. The log remains after revocation.

limit defaults to 100 and caps at 500.

{
  "reference": "9kq3m7vx2pf8dn",
  "count": 1,
  "usage": [
    {
      "capability": "payment_request",
      "amount": "5000",
      "currency": "USD",
      "operation_ref": "ledger-4412",
      "occurred_at": "2026-09-09T10:12:00Z"
    }
  ]
}

Delegations

A delegation authorises a third party — neither the grantor nor the grantee — to act inside a subset of a connection. The grantee already consumes the connection itself.

All four binds_to fields are required. Consume demands an exact match: a smaller amount is a different operation.

max_total defaults to the bound amount, which is one use. Set it higher for several identical operations — same amount, same destination.

`POST /connect/connections/{reference}/delegations`

Requires the local member credential. The caller is the grantor.

{
  "delegate": "member-c",
  "capability": "payment_request",
  "amount": "5000",
  "currency": "USD",
  "destination_commitment": "8f29a1c0e4b7d6f5a39281706c5e4d3b2a1908f7e6d5c4b3a2918071625344ab",
  "max_total": "15000",
  "expires_at": "2026-12-01T00:00:00Z"
}

{
  "reference": "d8k2m9pq3vx7",
  "delegate": "member-c",
  "status": "active",
  "binds_digest": "c41e…",
  "expires_at": "2026-12-01T00:00:00Z"
}

`GET /connect/delegations/{reference}`

Requires a member credential. Grantor, grantee of the parent connection, or the named delegate.

Read the terms from binds, the envelope signed at issuance. The outer signature is produced at read, because the counters move.

`POST /connect/delegations/{reference}/consume`

Requires a member credential. The caller is the named delegate. The body matches binds_to exactly.

{
  "capability": "payment_request",
  "amount": "5000",
  "currency": "USD",
  "destination_commitment": "8f29a1c0e4b7d6f5a39281706c5e4d3b2a1908f7e6d5c4b3a2918071625344ab",
  "operation_ref": "agent-19"
}

{
  "ok": true,
  "consumed_total": "5000",
  "consumed_operations": 1,
  "remaining_total": "10000",
  "parent_consumed_total": "130000",
  "parent_remaining_total": "370000"
}

The parent connection's ceilings apply as well as the token's.

`POST /connect/delegations/{reference}/revoke`

Requires a member credential. The grantor withdraws it, the delegate renounces it, or the parent grantee cuts it off. revoked_by records which.

`GET /connect/delegations/{reference}/usage`

Requires a member credential. Same shape as a connection's usage log, with destination_commitment on each row. limit defaults to 100 and caps at 500.

Connections

On this page