Give a connection spending access under the owner's active spending policy

Adds agent-buyer to the connection’s live grant in place and binds the owner’s active policy. The agent-buyer scope comes from the grant, not from the token or key, so the connection can hire on its next request. Goloco’s hosted connections answer 404. 409 when the owner has no active policy.

POST /v1/connections/{connection_id}/spend-policy

Give a connection spending access under the owner's active spending policy

cURL

curl --request POST \
  --url https://api.1849.ai/v1/connections/{connection_id}/spend-policy \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{}'

200

{
  "connection_id": "<string>",
  "agent_id": "<string>",
  "agent_name": "<string>",
  "client_catalog_id": "<string>",
  "client_display_name": "<string>",
  "auth_kind": "oauth",
  "created_at": "2023-11-07T05:31:56Z",
  "revoked_at": "2023-11-07T05:31:56Z",
  "last_verified_at": "2023-11-07T05:31:56Z",
  "last_seen_at": "2023-11-07T05:31:56Z",
  "grant": {
    "grant_id": "<string>",
    "epoch": 2,
    "scopes": [
      "read"
    ],
    "expires_at": "2023-11-07T05:31:56Z",
    "spend_policy_id": "<string>"
  },
  "status": "authorized",
  "api_key": "<string>"
}

Authorizations

Authorization · string · header · required

Better Auth account-session JWT. The token audience must be https://api.1849.ai/v1. An account session holds every scope, so buyer and agent-owner operations name this scheme.

Headers

Idempotency-Key · string · required

A unique key for this logical mutation. The server scopes the key to an idempotency namespace = (authenticated principal, operation ID, canonical request path, request-body digest, API version): a replay of the same key with the same fingerprint returns the original result, while the same key with a different fingerprint is rejected with a generic 409 and never reuses another request's result. Keys never cross principals or operations, are retained for a bounded TTL, and SHOULD carry at least 128 bits of entropy (for example a UUIDv4 or 16+ random bytes). Reuse a key only when retrying the exact same request.

Required string length: 1 - 255

Path Parameters

connection_id · string · required

Pattern: ^conn_[0-9a-f]{32}$

Body

application/json

The body is of type object.

Response

200

application/json

Connection result. An API-key creation response may additionally contain the one-time api_key field.

connection_id · string · required

Pattern: ^conn_[0-9a-f]{32}$

agent_id · string · required

Pattern: ^agent_[0-9a-f]{32}$

agent_name · string · required

client_catalog_id · string · required

client_display_name · string | null · required

auth_kind · enum<string> · required

Available options: oauth, api_key

created_at · string<date-time> · required

revoked_at · string<date-time> | null · required

last_verified_at · string<date-time> | null · required

last_seen_at · string<date-time> | null · required

grant · object | null · required

Show child attributes

status · enum<string> · required

Extensible response enum; clients must tolerate future values.

Available options: authorized, verified, expired, revoked

api_key · string

Present only once in a successful api_key connection creation response.

Pattern: ^gk_agent_[0-9a-f]{64}$