Connections API

A connection stores a provider credential (encrypted in the vault) plus its merchant config, scoped to your account and project. Connections are org-scoped resources under /v1/connections; sessions read them, they don't own them. The one session-scoped surface is the read-only list of what a given session can currently reach.

Base URL: https://api.codespar.dev

All endpoints require authentication via Bearer token. See Authentication.

POST /v1/connections

Creates a connection (or rotates the credential of an existing one for the same server_id/user_id). The secret is encrypted into the vault; it is never returned by any read endpoint.

Request body

Response -- 201 Created (or 200 OK on rotation)

{
  "id": "conn_abc123",
  "user_id": null,
  "server_id": "asaas",
  "auth_type": "api_key",
  "status": "connected",
  "display_name": "Asaas production",
  "metadata": {},
  "connection_metadata": { "default_customer_id": "cus_000042" },
  "cert_metadata": {},
  "created_at": "2026-07-01T12:00:00Z",
  "connected_at": "2026-07-01T12:00:00Z",
  "revoked_at": null,
  "expires_at": null
}

metadata is OAuth-derived provider metadata (set by callback flows); connection_metadata is your operator-supplied merchant config; cert_metadata is parsed X.509 info for cert-auth connections.

GET /v1/connections

Lists the project's connections, newest first.

Query parameters

Response -- 200 OK

{
  "connections": [ { "id": "conn_abc123", "server_id": "asaas", "status": "connected", "...": "..." } ]
}

GET /v1/connections/:id

Returns one connection (same shape as create). 404 not_found for unknown or cross-tenant ids. The secret is never included.

POST /v1/connections/:id/revoke

Marks the connection revoked AND purges the backing vault rows atomically — after revoke, the credential is gone at both the status gate and the vault lookup. The row itself remains for audit.

Response -- 200 OK

{ "id": "conn_abc123", "status": "revoked" }

Revoking an already-revoked connection returns { "id": "...", "status": "revoked", "already": true }.

PATCH /v1/connections/:id/metadata

Updates connection_metadata (merchant config) without touching the credential. Same 64-key / 32 KB cap as create.

PUT /v1/connections/:id/webhook-secret

Sets or rotates the provider webhook signing secret bound to this connection (used to verify inbound POST /v1/webhooks/:server_id/:connection_id deliveries).

DELETE /v1/connections/:id

Hard-deletes the connection row (vault rows included). Prefer revoke in production — it preserves the audit trail.

GET /v1/sessions/:id/connections

The session-scoped, read-only view: which providers this session can currently reach, with status and tool counts.

Auth required: Yes (scope: sessions:read)

curl example

curl https://api.codespar.dev/v1/sessions/ses_abc123/connections \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- 200 OK

{
  "data": [
    {
      "id": "stripe",
      "name": "Stripe",
      "category": "payments",
      "country": "GLOBAL",
      "auth_type": "api_key",
      "connected": true,
      "tools_count": 8,
      "status": "ready"
    },
    {
      "id": "mercadopago",
      "name": "Mercado Pago",
      "category": "payments",
      "country": "BR",
      "auth_type": "oauth",
      "connected": true,
      "tools_count": 6,
      "status": "ready"
    }
  ],
  "total": 2,
  "session_id": "ses_abc123"
}

Error codes

Next steps