# Connect a connector

One call to connect anything. The answer is `connected`, `authorization_required` with a URL to open, or `input_required` with the fields to collect — branch on `status`; there is no fourth. Credentials are write-only and never come back.

## POST `/v1/connectors/connections`

### 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`

### Query parameters

`team` string

min length 1 · max length 255

### Request body

required `application/json`

- `connector` string required
  - Connector slug to connect.
  - min length 1
- `owner` string required
  - Share it with the team, or keep it yours within this team.
  - Allowed: `team`, `personal`
- `displayName` string
  - What to call it. Defaults to the connector's title.
  - min length 1 · max length 255
- `description` string
  - Agent-visible note on what this connection is for.
  - max length 1000
- `authMethod` string
  - Which of the connector's auth methods to use. Required only when more than one could apply.
  - min length 1
- `credential` object
  - Omit it and the server tells you what it needs.
  - **Show properties**  
  One of:

- object
    - `kind` string required
    - `value` string required
      - The key. Write-only: sealed on arrival, never returned by any endpoint.
      - min length 1

- object
    - `kind` string required
    - `values` object required
      - Values keyed by the field names the connector asked for. Write-only, same as a key.

- `scopes` string[]
  - Narrow the authorization request below the method's defaults.
- `returnPath` string
  - Dashboard path to land on after authorization. Same-origin only; absolute URLs are rejected.
  - max length 512 · matches ^\/.*

### 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
  - The three ways connecting can end. Branch on `status`; there is no fourth.
  - **Show properties**
  One of:
  - object
    - `status` string required
      - Done. The connection is usable now.
    - `connection` object required
      - A configured instance of a connector, with a credential the control plane holds and never hands out.
      - **Show 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))$

### cURL Example

```bash
curl -X POST "https://api.spacefast.com/v1/connectors/connections" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "connector": "string",
  "owner": "team",
  "displayName": "string",
  "description": "string",
  "authMethod": "string",
  "credential": {
    "kind": "api_key",
    "value": "string"
  },
  "scopes": [
    "string"
  ],
  "returnPath": "string"
}'
```

### JavaScript Example

```javascript
const response = await fetch("https://api.spacefast.com/v1/connectors/connections", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"connector\": \"string\",\n  \"owner\": \"team\",\n  \"displayName\": \"string\",\n  \"description\": \"string\",\n  \"authMethod\": \"string\",\n  \"credential\": {\n    \"kind\": \"api_key\",\n    \"value\": \"string\"\n  },\n  \"scopes\": [\n    \"string\"\n  ],\n  \"returnPath\": \"string\"\n}"
});
```

### Python Example

```python
import requests

response = requests.post(
    "https://api.spacefast.com/v1/connectors/connections",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"connector\": \"string\",\n  \"owner\": \"team\",\n  \"displayName\": \"string\",\n  \"description\": \"string\",\n  \"authMethod\": \"string\",\n  \"credential\": {\n    \"kind\": \"api_key\",\n    \"value\": \"string\"\n  },\n  \"scopes\": [\n    \"string\"\n  ],\n  \"returnPath\": \"string\"\n}",
)
```

### Response Example

#### 200 Default Response

```json
{
  "$schema": "http://example.com",
  "data": {
    "status": "connected",
    "connection": {
      "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 Response 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"
}
```