---
title: "Create connection"
method: POST
path: "/connectors/v1/connections"
tags: ["Connectors"]
---

# Create connection

`POST /connectors/v1/connections`

## Request

- Base URL: `https://api.case.dev`
- URL: `https://api.case.dev/connectors/v1/connections`
- Auth: HTTP bearer

Create a pending provider connection and return a one-time connect_url for the hosted OAuth flow. The user completes provider consent at connect_url and is redirected to return_url with ?connection_id=.

## Headers

- `x-case-connector-subject` string

## Request body

- object
  - `provider` 'box' | 'clio' | 'dropbox' | 'gdrive' | 'microsoft' | 'smokeball', required
  - `return_url` string, required: HTTPS URL the user is sent back to after consent.
  - `scope_tier` 'box.readwrite' | 'box.readwrite.webhooks' | 'clio.us' | 'dropbox.readwrite' | 'drive' | 'microsoft.account.read' | 'microsoft.read' | 'microsoft.personal.read' | 'microsoft.write' | 'microsoft.personal.write' | 'smokeball.us' | 'smokeball.us.staging' | 'smokeball.us.staging.write' | 'smokeball.us.write': Provider-specific OAuth permission tier. Omit to use the provider's default. Use microsoft.account.read to let Microsoft choose a personal or work/school account. Existing explicit microsoft.read and microsoft.personal.read tiers remain supported. Microsoft write tiers require the separate write switch and explicit authorization for bounded exports and paired sync.

## Response `201`

Pending connection created

- object
  - `connection_id` string
  - `connect_url` string
  - `expires_at` string

## Other responses

- `400`: Unknown provider or invalid return_url
- `401`: Invalid API key
- `403`: Insufficient permissions
- `503`: Provider unavailable in this environment

## Changes

- **2026-10-27** `7ec75441c846`: 1 info
  - added the new `microsoft.account.read` enum value to the request property `scope_tier`
- **2026-10-20** `61ea97b43b26`: 1 info
  - added the new `smokeball.us.write` enum value to the request property `scope_tier`
- **2026-10-19** `1e12aa3dab04`: 1 info
  - added the non-success response with the status `503`
- **2026-10-16** `a21d188f4b21`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/casemark/apis/case-dev-api/changes/connectors/v1/connections/post.md)

---

[API](https://skmtc.dev/casemark/apis/case-dev-api.md) - [All operations](https://skmtc.dev/casemark/apis/case-dev-api/llms.txt) - [OpenAPI document](https://skmtc.dev/casemark/apis/case-dev-api/revisions/9a3245c00044?raw)