Connections

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

Every operation below requires a Bearer token. See Authentication.

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

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": "mercado-pago",
      "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

Every operation, from the spec

Generated from the published OpenAPI document, so it never drifts from what the API actually serves. The section above is written by hand and carries what a schema cannot: the object model, field rules, and the order to call things in.

GET /v1/connections

List the connections in this project

Active and historical both: a revoked or expired row stays for audit and is returned unless status filters it out. Newest first, capped by limit (default 50, maximum 100). The route does not paginate beyond that cap.

Scope is the calling credential's org AND project. A connection belonging to a sibling project of the same org is absent here and 404s on read, so this list and the point read agree.

Query parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/connections \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/connections HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/connections",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/connections", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/connections");

{
  "connections": [
    {
      "id": "obj_0000000000000000",
      "user_id": "user_0000000000000000",
      "server_id": "srv_0000000000000000",
      "auth_type": "string",
      "status": "pending",
      "display_name": "Example",
      "metadata": {},
      "connection_metadata": {},
      "cert_metadata": {},
      "is_shared_sandbox": true,
      "shared_sandbox_tools": [
        "string"
      ],
      "created_at": "2026-01-15T12:00:00.000Z",
      "connected_at": "2026-01-15T12:00:00.000Z",
      "revoked_at": "2026-01-15T12:00:00.000Z",
      "expires_at": "2026-01-15T12:00:00.000Z"
    }
  ]
}

POST /v1/connections

Register a provider key, or rotate the one already there

Encrypts secret and writes the connection in one transaction: either the ciphertext and the row both land, or neither does.

THIS ENDPOINT IS NOT AN INSERT. A status=connected connection for the same (org, project, server) makes the call a ROTATION: the vault entry is overwritten, display_name and connection_metadata are refreshed only when the body carries them, expires_at is cleared, and the EXISTING row comes back with 200. A first connection comes back with 201. user_id is not part of that identity, so a second team member reconnecting the same server rotates the shared credential rather than adding a second one.

secret takes two shapes and the server picks which one is legal from the catalog's auth_type. A plain string is for single-key providers. An object is for the multi-ref kinds (path_secret, cert, hmac_signed, jwt_ecdsa, two_header, cdp) and its keys must match the provider's declared refs EXACTLY: a missing or extra key is 400 path_secret_keys_mismatch with both lists, never a silent drop, because dropping one leaves the provider unusable at call time with no trace of why.

OAuth providers are refused here with 400 not_api_key_server; they go through POST /v1/connections/start. An unknown catalog id is 404 server_unknown. A provider whose catalog row declares no refs is 500 endpoint_missing_refs, which is a seed defect on our side and not a bad request.

Service-auth callers must send x-codespar-user and hold admin or above. Bearer callers are gated by possession of the key alone. The secret is never echoed back by this or any other operation.

Request body

Responses

Response 200

curl -X POST https://api.codespar.dev/v1/connections \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "server_id": "srv_0000000000000000",
       "secret": "string",
       "display_name": "Example",
       "user_id": "user_0000000000000000",
       "connection_metadata": {}
     }'

POST /v1/connections HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json

{
  "server_id": "srv_0000000000000000",
  "secret": "string",
  "display_name": "Example",
  "user_id": "user_0000000000000000",
  "connection_metadata": {}
}

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/connections",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "server_id": "srv_0000000000000000",
      "secret": "string",
      "display_name": "Example",
      "user_id": "user_0000000000000000",
      "connection_metadata": {}
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/connections", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "server_id": "srv_0000000000000000",
    "secret": "string",
    "display_name": "Example",
    "user_id": "user_0000000000000000",
    "connection_metadata": {}
  }),
});

const data = await res.json();

const r = await cs.api.response("post", "/v1/connections", {
  body: {
    server_id: "srv_0000000000000000",
    secret: "string",
    display_name: "Example",
    user_id: "user_0000000000000000",
    connection_metadata: {}
  }
});
// r.status is one of the documented statuses (200, 403),
// each with its own body shape in r.data; nothing here throws on 403.
if (r.ok) {
  console.log(r.data);
}

{
  "id": "obj_0000000000000000",
  "user_id": "user_0000000000000000",
  "server_id": "srv_0000000000000000",
  "auth_type": "string",
  "status": "pending",
  "display_name": "Example",
  "metadata": {},
  "connection_metadata": {},
  "cert_metadata": {},
  "is_shared_sandbox": true,
  "shared_sandbox_tools": [
    "string"
  ],
  "created_at": "2026-01-15T12:00:00.000Z",
  "connected_at": "2026-01-15T12:00:00.000Z",
  "revoked_at": "2026-01-15T12:00:00.000Z",
  "expires_at": "2026-01-15T12:00:00.000Z"
}

GET /v1/connections/engine/{run_id}/status

Poll a browser-driven signup run

Read-only. The run resolves only inside the calling credential's org and project, so a run id from another tenant is 404 rather than 403.

Poll this while status is running. When it becomes needs_verification the customer has to clear the provider's email gate, and verification.mechanism says how: code means a one-time code to relay, link means a link to click in their own inbox. Branch on the mechanism, never on the provider name. A paused run that has expired answers 410 run_stale and cannot be resumed.

On provisioned, connection_id names the connection the run produced, which then behaves like any other row on this resource. On failed, code is drawn from a closed first-party vocabulary and failed_step_id names the step, when the run recorded one; a failed run that recorded no reason reports its status alone. The bounded failure detail, the page URL and the screenshot references are deliberately not selected by this query, so they cannot leak from it.

The 404 body here is { error: { code, message } } with no request_id, unlike the 410 beside it.

Path parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/connections/engine/{run_id}/status \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/connections/engine/{run_id}/status HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/connections/engine/{run_id}/status",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/connections/engine/{run_id}/status", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/connections/engine/{run_id}/status", {
  path: {
    run_id: "run_0000000000000000"
  }
});

{
  "status": "running",
  "prompt": "string",
  "verification": {
    "mechanism": "code",
    "resend": true
  },
  "connection_id": "conn_0000000000000000",
  "code": "flow_failed",
  "failed_step_id": "failedstep_0000000000000000"
}

POST /v1/connections/start

Begin the Connect Link OAuth flow for a provider

The entry point for providers that cannot be connected by posting a key. It mints a single-use state token, stores the caller's org, project and environment against it, and returns the provider's authorize URL with that token already embedded.

Send the user to authorize_url. The provider redirects to our callback, which exchanges the code, vaults the tokens under the project recorded at start, revokes any existing connection for the same (project, user, server) and writes the new one. The callback is not part of this document: it is unauthenticated by necessity, since the provider carries no CodeSpar credential.

link_token is the same value as the state parameter inside authorize_url; it is single use and expires at expires_at, ten minutes out. redirect_uri must be https and is where the callback sends the browser back, with status=connected&connection_id=…, status=denied&error=… or status=error&error=… appended.

POST /v1/connect/start is the same handler on a second path. A provider with no OAuth configuration is 404; a missing platform client credential is 500, which is our seeding defect and not the caller's error. Both bodies are bare { error, … }, not the error.code envelope.

Request body

Responses

Response 200

curl -X POST https://api.codespar.dev/v1/connections/start \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "server_id": "srv_0000000000000000",
       "user_id": "user_0000000000000000",
       "redirect_uri": "https://example.com/hook",
       "scopes": "string"
     }'

POST /v1/connections/start HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json

{
  "server_id": "srv_0000000000000000",
  "user_id": "user_0000000000000000",
  "redirect_uri": "https://example.com/hook",
  "scopes": "string"
}

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/connections/start",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "server_id": "srv_0000000000000000",
      "user_id": "user_0000000000000000",
      "redirect_uri": "https://example.com/hook",
      "scopes": "string"
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/connections/start", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "server_id": "srv_0000000000000000",
    "user_id": "user_0000000000000000",
    "redirect_uri": "https://example.com/hook",
    "scopes": "string"
  }),
});

const data = await res.json();

const r = await cs.api.response("post", "/v1/connections/start", {
  body: {
    server_id: "srv_0000000000000000",
    user_id: "user_0000000000000000",
    redirect_uri: "https://example.com/hook",
    scopes: "string"
  }
});
// r.status is one of the documented statuses (200, 422),
// each with its own body shape in r.data; nothing here throws on 422.
if (r.ok) {
  console.log(r.data);
}

{
  "link_token": "string",
  "authorize_url": "https://example.com/hook",
  "expires_at": "2026-01-15T12:00:00.000Z"
}

POST /v1/connections/subaccount/{id}/revoke

Revoke a provisioned subaccount and try to delete it upstream

The revoke for accounts this platform minted on the customer's behalf. It is not POST /v1/connections/{id}/revoke: the generic purge targets the ref keyed on the server id, which is the wrong ref for a per-account subaccount credential, and it touches neither the provisioning record nor the account at the provider.

Local teardown first, atomically: the connection projection flips, the provisioning record flips, and the correct per-account vault ref is purged. A failure in that phase changes nothing and answers 503, so a retry is safe. Only then is a delete attempted at the provider.

READ upstream BEFORE TREATING THIS AS FINISHED. deleted means the account is gone at the provider. not_applicable means the lane has no delete to make. delete_failed and orphaned mean the credential is destroyed on our side but an account may still exist upstream, and closing it is a manual step. All four come back with 200, because the local teardown did succeed.

{id} is a connection id for the customer path, matched only inside the caller's own org and project. It is a provisioning record id for the operator-internal path, which additionally requires service auth. A customer credential can never reach an operator-internal record: it misses the connection lookup and gets 404, never a 403 that would confirm the id exists. A repeated revoke returns already: true and changes nothing.

Path parameters

Responses

Response 200

curl -X POST https://api.codespar.dev/v1/connections/subaccount/{id}/revoke \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

POST /v1/connections/subaccount/{id}/revoke HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/connections/subaccount/{id}/revoke",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/connections/subaccount/{id}/revoke", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const r = await cs.api.response("post", "/v1/connections/subaccount/{id}/revoke", {
  path: {
    id: "subaccount_0000000000000000"
  }
});
// r.status is one of the documented statuses (200, 403),
// each with its own body shape in r.data; nothing here throws on 403.
if (r.ok) {
  console.log(r.data);
}

{
  "status": "revoked",
  "record_id": "record_0000000000000000",
  "connection_id": "conn_0000000000000000",
  "upstream": "deleted",
  "already": true
}

GET /v1/connections/subaccount/{id}/status

Read whether a provisioned subaccount can transact yet

Read-only, with one live call to the provider. It writes nothing and changes no state.

charges_enabled is what the provider says right now, not a cached flag, which is why a provider that is unreachable answers 502 rather than a stale false. The one exception is a revoked record: it short-circuits to status: "revoked" and charges_enabled: false without calling the provider at all, since there is nothing left to poll. A confirmed account that never reached an upstream account ref reports not-yet-chargeable for the same reason.

capabilities carries the provider's per-capability activation states when it reports them, and is absent when it does not. An account can be provisioned and still not chargeable; gate any money movement on charges_enabled, not on the existence of the connection.

Same dual-id resolution and same cross-tenant 404 as the revoke beside it, minus its admin floor: a read does not need one.

Path parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/connections/subaccount/{id}/status \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/connections/subaccount/{id}/status HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/connections/subaccount/{id}/status",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/connections/subaccount/{id}/status", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/connections/subaccount/{id}/status", {
  path: {
    id: "subaccount_0000000000000000"
  }
});

{
  "status": "provisioned",
  "charges_enabled": true,
  "capabilities": {},
  "account_ref": "string"
}

GET /v1/connections/{id}

Read one connection

404 covers three different situations and deliberately does not distinguish them: no such id, an id owned by another org, and an id owned by a sibling project of the same org. Answering 403 for the last two would confirm the id exists.

Path parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/connections/{id} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/connections/{id} HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/connections/{id}",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/connections/{id}", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/connections/{id}", {
  path: {
    id: "conn_0000000000000000"
  }
});

{
  "id": "obj_0000000000000000",
  "user_id": "user_0000000000000000",
  "server_id": "srv_0000000000000000",
  "auth_type": "string",
  "status": "pending",
  "display_name": "Example",
  "metadata": {},
  "connection_metadata": {},
  "cert_metadata": {},
  "is_shared_sandbox": true,
  "shared_sandbox_tools": [
    "string"
  ],
  "created_at": "2026-01-15T12:00:00.000Z",
  "connected_at": "2026-01-15T12:00:00.000Z",
  "revoked_at": "2026-01-15T12:00:00.000Z",
  "expires_at": "2026-01-15T12:00:00.000Z"
}

DELETE /v1/connections/{id}

Delete a revoked connection for good

Hard delete, allowed only once status is revoked or expired. An active connection is refused with 409 rather than deleted, because dropping the row while the credential still works would lose the audit trail and leave the vault entry with nothing pointing at it.

The purge runs inside the same transaction, before the row goes. That matters for an expired connection, which reaches here without ever having been revoked and so has never been purged; for an already-revoked one the purge is a no-op.

The 409 body is a bare { error, message } pair, not the error.code envelope the newer routes use.

Path parameters

Responses

curl -X DELETE https://api.codespar.dev/v1/connections/{id} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

DELETE /v1/connections/{id} HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.delete(
    "https://api.codespar.dev/v1/connections/{id}",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/connections/{id}", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.delete("/v1/connections/{id}", {
  path: {
    id: "conn_0000000000000000"
  }
});

PATCH /v1/connections/{id}/metadata

Merge user-editable metadata into a connection

Merges fields into a connection's connection_metadata. This is a merge, not a replacement: the keys sent land on top and the rest stay.

What can be edited is decided by the row itself, by the requires_user_fields list it carries. A key outside that list is refused with fields_not_user_editable, and a connection that carries no list at all refuses EVERY patch with no_user_fields. Its path is to reconnect, not to edit.

Path parameters

Request body

Responses

Response 200

curl -X PATCH https://api.codespar.dev/v1/connections/{id}/metadata \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "connection_metadata": {}
     }'

PATCH /v1/connections/{id}/metadata HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json

{
  "connection_metadata": {}
}

import os
import requests

res = requests.patch(
    "https://api.codespar.dev/v1/connections/{id}/metadata",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "connection_metadata": {}
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/connections/{id}/metadata", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "connection_metadata": {}
  }),
});

const data = await res.json();

const result = await cs.api.patch("/v1/connections/{id}/metadata", {
  path: {
    id: "conn_0000000000000000"
  },
  body: {
    connection_metadata: {}
  }
});

{
  "id": "obj_0000000000000000",
  "user_id": "user_0000000000000000",
  "server_id": "srv_0000000000000000",
  "auth_type": "string",
  "status": "pending",
  "display_name": "Example",
  "metadata": {},
  "connection_metadata": {},
  "cert_metadata": {},
  "is_shared_sandbox": true,
  "shared_sandbox_tools": [
    "string"
  ],
  "created_at": "2026-01-15T12:00:00.000Z",
  "connected_at": "2026-01-15T12:00:00.000Z",
  "revoked_at": "2026-01-15T12:00:00.000Z",
  "expires_at": "2026-01-15T12:00:00.000Z"
}

POST /v1/connections/{id}/revoke

Revoke a connection and destroy its stored credential

Flips the row to revoked AND deletes the vault rows behind it, in one transaction. The row survives because audit needs connected_at after the credential is gone; the ciphertext does not. A revoke that could not purge fails with 503 and leaves the connection connected, which is the honest outcome: reporting revoked while the secret stays decryptable is the failure this route exists to prevent.

A vault entry is dropped only when no other still-connected row in the same org and project would resolve it. Sibling providers can share one bundle, so a shared key survives until the last connection using it is revoked.

TWO DIFFERENT 200 BODIES. A revoke that did work returns the full connection row. A connection already revoked returns the short { id, status, already } form and touches nothing, so a retry is safe. Branch on the presence of already, not on the status code.

Path parameters

Responses

curl -X POST https://api.codespar.dev/v1/connections/{id}/revoke \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

POST /v1/connections/{id}/revoke HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/connections/{id}/revoke",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/connections/{id}/revoke", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.post("/v1/connections/{id}/revoke", {
  path: {
    id: "conn_0000000000000000"
  }
});

{
  "id": "obj_0000000000000000",
  "user_id": "user_0000000000000000",
  "server_id": "srv_0000000000000000",
  "auth_type": "string",
  "status": "pending",
  "display_name": "Example",
  "metadata": {},
  "connection_metadata": {},
  "cert_metadata": {},
  "is_shared_sandbox": true,
  "shared_sandbox_tools": [
    "string"
  ],
  "created_at": "2026-01-15T12:00:00.000Z",
  "connected_at": "2026-01-15T12:00:00.000Z",
  "revoked_at": "2026-01-15T12:00:00.000Z",
  "expires_at": "2026-01-15T12:00:00.000Z"
}

PUT /v1/connections/{id}/webhook-secret

Seed or rotate the secret that verifies this provider's inbound webhooks

The value a provider signs its callbacks with (a Stripe signing secret, an Asaas access token, a Zoop Basic blob). The vault ref is derived from the provider internally, so a caller never has to know the naming convention.

Write-only: the plaintext is accepted once and no operation returns it. updated is the only thing the response says about the previous state, and it says exactly one thing: true when a secret was already stored under that ref, false when this call seeded the first one.

A provider with no inbound webhook adapter is refused with 400 provider_has_no_inbound_webhooks, since a secret nothing will ever verify is worse than no secret at all. This write is not transactional with anything else: a 503 means the vault write failed and the old secret, if any, is still in place.

Path parameters

Request body

Responses

Response 200

curl -X PUT https://api.codespar.dev/v1/connections/{id}/webhook-secret \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "secret": "string"
     }'

PUT /v1/connections/{id}/webhook-secret HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json

{
  "secret": "string"
}

import os
import requests

res = requests.put(
    "https://api.codespar.dev/v1/connections/{id}/webhook-secret",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "secret": "string"
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/connections/{id}/webhook-secret", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "secret": "string"
  }),
});

const data = await res.json();

const result = await cs.api.put("/v1/connections/{id}/webhook-secret", {
  path: {
    id: "conn_0000000000000000"
  },
  body: {
    secret: "string"
  }
});

{
  "connection_id": "conn_0000000000000000",
  "server_id": "srv_0000000000000000",
  "updated": true
}