---
title: "Start a connection"
method: POST
path: "/connections/connect"
tags: ["Connections"]
---

# Start a connection

`POST /connections/connect`

## Request

- Base URL: `https://api.crevio.co/v1`
- URL: `https://api.crevio.co/v1/connections/connect`
- Auth: API key in header `Authorization`

Mint a hosted OAuth link to connect an app; send the user to `redirect_url`. Some apps need setup first (see `setup_fields`). On return the connection appears in GET /connections.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `toolkit` string, required: App slug from the catalog (e.g. gmail)
  - `callback_url` string: Where to return the user after auth
  - `scope` 'account' | 'user': Who owns the resulting connection. `account` (default) shares it with the whole workspace; `user` makes it personal to the authenticated user and invisible to teammates.

## Response `200`

Success

- ConnectionLink
  - `object` 'connection_link', required
  - `status` 'INITIATED', required
  - `toolkit` string, required
  - `redirect_url` string, required: Hosted OAuth URL to send the user to
  - `external_account_id` string
  - `expires_at` string, nullable
  - `setup_fields` object[]: Fields the connect page asks the user for besides the OAuth login (e.g. Shopify's shop ID and the client ID/secret of a custom app they must create first, with the redirect URI to register). Empty for plain OAuth apps. Walk the user through these before sending them to `redirect_url`.
    - `name` string, required
    - `label` string, nullable
    - `description` string, nullable: Setup instructions for this field, in Markdown
    - `optional` boolean, required

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Forbidden
- `422`: Validation error
- `429`: Rate limit exceeded — 600 requests per minute per credential. Retry after the number of seconds in `Retry-After`.
- `500`: Internal server error
- `503`: Feature not configured for this workspace

---

[API](https://skmtc.dev/crevio/apis/crevio-api-v1.md) · [All operations](https://skmtc.dev/crevio/apis/crevio-api-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/crevio/apis/crevio-api-v1/revisions/2219f18ad651?raw)