# Update a connection

Renames a connection or replaces the agent-visible note on what it is for. Credentials are immutable: to rotate one, reconnect.

## PATCH `/v1/connectors/connections/{connectionId}`

### Authorization

`Authorization` Bearer token · header required

`Authorization: Bearer <token>` with an API key (`sfa_` prefix), an OAuth access token, a session token, or a Space machine credential (`sfm_` prefix).

or  
`Authorization` OAuth2 access token · header required

OAuth 2.0 with Spacefast scopes. People use the authorization code flow; machines use client credentials.

**Scopes:** `connectors:write`

### Path parameters

- `connectionId` string required  
  min length 1

### Query parameters

- `team` string  
  min length 1 · max length 255

### Request body

required `application/json`

- `displayName` string  
  Replacement label.  
  min length 1 · max length 255
- `description` string | any  
  Replacement agent-visible description.

### Responses

#### 200 Response for status 200

- `$schema` string <uri>  
  Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.
- `data` object required  
  A configured instance of a connector, with a credential the control plane holds and never hands out.

#### Properties

- `id` string required  
  Connection id (`cxn_`). This is also the first segment of every tool address it owns.
- `connector` string required  
  Slug of the connector this connection authenticates.
- `owner` string required  
  `team` is shared with everyone on the team; `personal` is yours, and only within this team — connecting the same account for another team is another connection.
  Allowed: `team`, `personal`
- `displayName` string required  
  What people call this connection, e.g. "Linear (support)".
- `description` string | any required  
  Agent-visible note on what this connection is for. Shown to models choosing between several.
- `status` string required  
  Derived connection state. Never stored, so it cannot drift from the credential it describes.
  Allowed: `pending_authorization`, `active`, `degraded`, `needs_reauth`, `revoked`
- `identityLabel` string | any required  
  Account label reported by the provider, when it identifies itself. Null until the first successful probe.
- `credentialConfigured` boolean required  
  Whether a usable credential is stored. The credential itself is never returned by any endpoint.
- `authMethod` string | any required  
  Slug of the connector auth method this connection used.
- `scopes` string[] required  
  Scopes actually granted, when the provider reports them.
- `isDefault` boolean required  
  Whether this is the connection an agent gets when it names the connector alone.
- `toolCount` integer required  
  Tools reachable through this connection at the last sync.  
  min -9007199254740991 · max 9007199254740991
- `createdBy` string | any required  
  User who connected it; null for first-party connections Spacefast owns.
- `lastCheckedAt` string <date-time> | any required  
  Last health probe.
- `revokedAt` string <date-time> | any required  
  When it was disconnected. The credential is purged; the row tombstones.
- `createdAt` string <date-time> required  
  matches ^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$
- `updatedAt` string <date-time> required  
  matches ^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$

### Error Response

- `$schema` string <uri>  
  Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.
- `type` string required  
  URL of the documentation page for this error. Derived from `code`.
- `title` string required  
  Human-readable name of the error type. Derived from `code`.
- `status` integer required  
  HTTP status of the response, repeated in the body.
  min -9007199254740991 · max 9007199254740991
- `detail` string required  
  What went wrong in this request.
- `code` string required  
  Stable snake_case error code. Match on this, not on `detail`.
- `pointer` string  
  RFC 6901 JSON Pointer to the request field or batch entry that failed, for example `/files/37/path`. Present on validation failures.
- `details` object  
  Machine-readable context keyed by the error code.
- `suggestions` string[]  
  Recovery steps safe to show to a person.
- `next` string[]  
  Commands or API requests to run next, usable as written.
- `requestId` string required  
  ID of this request, from the `X-Request-Id` header or generated. Quote it when contacting support.

### Try it

#### Server

Base URL  https://api.spacefast.com
Custom base URL  Overrides the selected server when set.

### Parameters

- `connectionId` path*  
- `team` query

### Body

application/json

- `displayName` string  
  Replacement label.  
- `description` string  
  Replacement agent-visible description.

### Send

#### Request

**cURL**
```bash
curl -X PATCH "https://api.spacefast.com/v1/connectors/connections/string" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{\n  "displayName": "string",\n  "description": "string"\n}'
```

**JavaScript**
```javascript
const response = await fetch("https://api.spacefast.com/v1/connectors/connections/string", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"displayName\": \"string\",\n  \"description\": \"string\"\n}"
});
```

**Python**
```python
import requests

response = requests.patch(
    "https://api.spacefast.com/v1/connectors/connections/string",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"displayName\": \"string\",\n  \"description\": \"string\"\n}",
)
```

### Response

#### 200 Default
```json
{
  "$schema": "http://example.com",
  "data": {
    "id": "string",
    "connector": "string",
    "owner": "team",
    "displayName": "string",
    "description": "string",
    "status": "pending_authorization",
    "identityLabel": "string",
    "credentialConfigured": true,
    "authMethod": "string",
    "scopes": [\
      "string"\
    ],
    "isDefault": true,
    "toolCount": -9007199254740991,
    "createdBy": "string",
    "lastCheckedAt": "2019-08-24T14:15:22Z",
    "revokedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
```

#### Error Example
```json
{
  "$schema": "http://example.com",
  "type": "string",
  "title": "string",
  "status": -9007199254740991,
  "detail": "string",
  "code": "string",
  "pointer": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "suggestions": [\
    "string"\
  ],
  "next": [\
    "string"\
  ],
  "requestId": "string"
}
```