Connect a connector - Spacefast Docs

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).

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
- 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
      | any required
      
      Last health probe.
    - revokedAt string
      | any required
      
      When it was disconnected. The credential is purged; the row tombstones.
    - createdAt string
      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
      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

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

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

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

{
  "$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

{
  "$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"
}