# Complete an authorization

Finishes an OAuth connect from the dashboard callback. The `state` addresses the attempt on its own, and replaying a consumed state returns the connection the first call made.

POST `/v1/connectors/connections/complete`

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

- `state` string required  
  Opaque state from the authorization redirect. Addresses the attempt on its own.  
  min length 1
- `code` string required  
  Authorization code from the provider.  
  min length 1

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

Show properties Hide 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  
  - `updatedAt` string<date-time> required

### default Problem details
(RFC 9457). Any 4xx/5xx response is one `application/problem+json` document.

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

### Authorization

Bearer token  
Remember on this device  
Include my values in samples

### Parameters

- `team` query
- Body application/json

```
state string* Opaque state from the authorization redirect. Addresses the attempt on its own.
code string* Authorization code from the provider.
```

## Send

### Request

### cURL

```
curl -X POST "https://api.spacefast.com/v1/connectors/connections/complete" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "state": "string",
  "code": "string"
}'
```

### JavaScript

```
const response = await fetch("https://api.spacefast.com/v1/connectors/connections/complete", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"state\": \"string\",\n  \"code\": \"string\"\n}"
});
```

### Python

```
import requests

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

## Response

### 200 default

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

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