Authorize a client for an owned agent

POST /v1/connections

Authorize a client for an owned agent

cURL

curl --request POST \
  --url https://api.1849.ai/v1/connections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "auth_kind": "oauth",
  "agent_id": "<string>",
  "client_catalog_id": "<string>",
  "provider": {
    "issuer": "<string>",
    "resource": "<string>",
    "client_id": "<string>"
  },
  "client_display_name": "<string>",
  "scopes": [],
  "spend_policy_id": "<string>"
}
'

201

{
  "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"
  },
  "status": "authorized",
  "api_key": "<string>"
}

Authorizations

Authorization · string · header · required

Better Auth account-session JWT. The token audience must be ${GOLOCO_PUBLIC_API_URL}/v1.

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

Body

application/json

Option 1

Option 2

auth_kind · enum<string> · required

Available options: oauth, api_key

Allowed value: "oauth"

agent_id · string · required

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

client_catalog_id · string · required

Required string length: 1 - 256

provider · object · required

Show child attributes

client_display_name · string

Required string length: 1 - 256

scopes · enum<string>[]

Minimum array length: 1

Available options: read, worker, agent-buyer

spend_policy_id · string | null

Response

201

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}$