Update a connection

Changes a connection's label, subject, params, bound hosts (custom connections only) or metadata, or replaces its secret (all fields at once, for rotation). Omitted fields are unchanged. In-flight calls finish with the old secret; new calls use the new one. Concurrent updates of one connection apply one after another; 409 `conflict` means the connection kept changing while this update ran (read it and try again).

PATCH /v1/vault/connections/{connection_id}
Changes a connection's label, subject, params, bound hosts (custom connections only) or metadata, or replaces its secret (all fields at once, for rotation). Omitted fields are unchanged. In-flight calls finish with the old secret; new calls use the new one. Concurrent updates of one connection apply one after another; 409 `conflict` means the connection kept changing while this update ran (read it and try again).

Authentication

Bearer Token (b3os_sk_ API key or b3os_pat_ token) API Key (cookie: __Host-b3os_session)

Path Parameters

connection_id string required path
The connection ID (`conn_…`).
Example: "conn_01m5t6cbgdjs1ketgcqwa2sne8"

Request Body required

application/json
label string
subject string | null
hosts string[]
Connections without a pack only. `[]` makes the connection verification-only (never injected).
Array of: string
params object
secret object
Secret fields for the connection's type. Write-only: accepted on create and update, never returned or logged.
api_key string
username string
password string
token string
access_token string
refresh_token string
expires_at string (date-time)
When `access_token` expires (oauth2).
client_id string
client_secret string
metadata object
Up to 16 string key-value pairs you attach to an object for your own use. Keys are 1 to 40 characters of `A-Z a-z 0-9 _ . : -`; values are at most 500 characters. B3OS never interprets them.

Responses

200 The updated connection.
application/json
id string REQUIRED
object string REQUIRED
Enum: connection
pack string | null REQUIRED
key string | null REQUIRED
type string REQUIRED
The credential kind, as in pack manifests.
Enum: api_key, basic, bearer, oauth2, none
label string | null REQUIRED
subject string | null REQUIRED
hosts string[] REQUIRED
Hosts that receive the credential; `[]` for a verification-only connection (never injected).
Array of: string
params object REQUIRED
secret_fields string[] REQUIRED
Names of the stored secret fields.
Array of: string
status string REQUIRED
`expired` when an OAuth access token passed `expires_at` and could not be refreshed.
Enum: active, expired
expires_at string (date-time) | null REQUIRED
created_at string (date-time) REQUIRED
updated_at string (date-time) REQUIRED
last_used_at string (date-time) | null REQUIRED
metadata object REQUIRED
Up to 16 string key-value pairs you attach to an object for your own use. Keys are 1 to 40 characters of `A-Z a-z 0-9 _ . : -`; values are at most 500 characters. B3OS never interprets them.
400 The request failed validation (`invalid_request`, `invalid_url`).
401 Missing, malformed, expired or revoked credentials (`unauthorized`).
403 Authenticated but not allowed (`forbidden`, `egress_denied`).
404 No such connection in this project (`connection_not_found`).
409 The connection kept changing while this update ran (`conflict`); read it and try again.
413 The request body exceeds this operation's limit.
415 The Content-Type is not accepted by this operation.
422 The secret fields or hosts do not fit the type (`connection_invalid`).
429 A rate, concurrency or quota limit applies (`rate_limited`, `concurrency_limited`, `quota_exceeded`).
500 Something failed inside B3OS (`internal`). Retry with backoff.
503 The node or the product is not available right now (`node_unavailable`, `product_unavailable`, `capacity_unavailable`). 
curl -X PATCH 'https://beta-api.b3os.org/v1/vault/connections/conn_01m5t6cbgdjs1ketgcqwa2sne8' \  -H 'Authorization: Bearer YOUR_API_TOKEN' \  -H 'Content-Type: application/json' \  -d '{  "secret": {    "token": "<rotated github token>"  }}'
const response = await fetch('https://beta-api.b3os.org/v1/vault/connections/conn_01m5t6cbgdjs1ketgcqwa2sne8', {  method: 'PATCH',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN",      "Content-Type": "application/json"  },  body: JSON.stringify({    "secret": {      "token": "<rotated github token>"    }  })});const data = await response.json();console.log(data);
import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.patch('https://beta-api.b3os.org/v1/vault/connections/conn_01m5t6cbgdjs1ketgcqwa2sne8', headers=headers, json={  "secret": {    "token": "<rotated github token>"  }})print(response.json())
200 Response 
{  "id": "conn_01m5t6cbgdjs1ketgcqwa2sne8",  "object": "connection",  "pack": "io.b3os/github",  "key": "api",  "type": "bearer",  "label": "CI bot token",  "subject": null,  "hosts": [    "api.github.com"  ],  "params": {},  "secret_fields": [    "token"  ],  "status": "active",  "expires_at": null,  "created_at": "2026-10-25T20:10:00.000Z",  "updated_at": "2026-10-25T20:30:00.000Z",  "last_used_at": "2026-10-25T20:12:41.000Z",  "metadata": {}}
Previous Get a connection
Next Delete a connection
Ask a question... ⌘I