Connect or reconfigure a channel

Record this workspace's connection for a channel, creating it or replacing it wholesale.

This is a replace, not a merge. config is written wholesale, so a save that omits a key deletes it. Send the whole configuration every time, and remember that a read gives you redacted values, so do not write back what you just read: *** would be stored literally.

A connection may be stored for a channel whose adapter does not exist yet. The connection records intent and configuration, and GET /v1/channels reports adapter_available: false until an adapter ships.

Config values are treated as credentials: everything except a short allowlist of operator descriptors is returned redacted on every read.

An OAuth token in config is refused with 400 channel_credential_misplaced rather than stored, because this field is replaced in full on every save and a cleared refresh token cannot be typed back in by anyone. The refusal names the route that stores it properly.

A stored connection does not mean traffic is flowing. It records what an operator configured.

Tenancy: the request is scoped to one workspace, and the credential presented is what selects it. A caller with no membership in that workspace is refused with 404, which is indistinguishable from a workspace that does not exist.

Authorisation: editor, admin or owner. A viewer receives 403 insufficient_role.

Access: Authorization: Bearer carrying either a realm access token or an API key. A key must hold the channels:write scope, and the workspace role of the person who owns it must meet the floor above.

Path Parameters

Response Body

curl -X PUT "https://example.com/v1/channels/string" \  -H "Content-Type: application/json" \  -d '{    "enabled": true,    "display_name": "Support SMS",    "config": {      "from_number": "+15550199",      "auth_token": "the provider\'s token"    }  }'

{  "channel": "sms",  "display_name": "Support SMS",  "adapter_available": true,  "ticket_source": "sms",  "handle_kind": "phone_number",  "outbound_supported": false,  "inbound_path": "/v1/ingest/sms",  "details": {},  "connected": true,  "enabled": true,  "config": {    "from_number": "+15550199",    "auth_token": "***"  },  "created_at": "2026-05-19T15:22:00+00:00",  "updated_at": "2026-08-14T08:10:00+00:00"}