Connect an Account

Connecting a provider account takes three steps:

Create a pending connection and get a one-time connect_url
Send the user to it—they consent at the provider
Handle the return at your own URL, which now carries the connection id

Your server never sees an authorization code, an access token, or a refresh token.

Step 1: Create the connection

Endpoint

POST /connectors/v1/connections

cURL

curl -X POST https://api.case.dev/connectors/v1/connections \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "clio",
    "return_url": "https://app.example.com/integrations/callback"
  }'

Response

{
  "connection_id": "conn_abc123",
  "connect_url": "https://api.case.dev/connectors/v1/connect/QTd2…",
  "expires_at": "2026-01-15T10:40:00Z"
}

Field	Required	Description
`provider`	yes	`clio` or `gdrive`
`return_url`	yes	Where the user lands after consent
`scope_tier`	no	Provider permission tier. Omit to use the provider’s default.

The connection exists immediately with status pending. It becomes healthy only after the user finishes consent.

return_url rules

The URL is validated when you create the connection, not when the user comes back. A URL that fails these checks returns 400.

It must be absolute.
It must use https. localhost and 127.0.0.1 over http are accepted outside production.
It must not embed credentials (no user:password@host).

Case.dev appends a query parameter to whatever you supply, preserving your existing ones.

Treat return_url as a redirect target you own. Do not build it from unvalidated user input, and do not point it at a URL that forwards onward using a parameter an attacker controls.

Scope tiers

scope_tier selects a provider permission level. Both current providers expose a single tier (clio.us, drive), so omit the field and you get it by default. The tier is signed into the connect_url, so a user cannot broaden their own consent by editing the query string before they click through.

Step 2: Send the user to connect_url

Redirect the browser to connect_url. Case.dev builds the provider authorization URL, attaches HMAC-signed state and a PKCE challenge, and forwards the user to the provider’s consent screen.

connect_url is one-time and expires in 10 minutes. An expired link returns 410; a link that has already been used returns 404. Generate it when the user is about to click, not when the page loads.

Step 3: Handle the return

After consent, the provider redirects to Case.dev, which exchanges the code, stores the encrypted tokens, and sends the user to your return_url.

Success

https://app.example.com/integrations/callback?connection_id=conn_abc123

Failure

https://app.example.com/integrations/callback?error=connector_scope_not_enabled

Branch on which parameter is present.

`error` value	Meaning	What to do
`access_denied`	The user declined consent at the provider	Offer to try again
`provider_error`	The provider returned an error before issuing a code	Retry; escalate if it persists
`missing_code`	The provider redirected without an authorization code	Retry
`connector_scope_not_enabled`	The provider is not enabled for your organization, or the user granted fewer scopes than required	Contact support, or ask the user to reconnect and accept the full consent
`oauth_flow_inactive`	The pending connection was disconnected, superseded, or did not match the initiating session	Start a fresh connection
`oauth_exchange_failed`	The code exchange with the provider failed	Retry; escalate if it persists

On success, confirm the connection is usable before you show it as connected:

cURL

curl https://api.case.dev/connectors/v1/connections/conn_abc123 \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

Response

{
  "id": "conn_abc123",
  "provider": "clio",
  "status": "healthy",
  "enabled": true,
  "scope_tier": "clio.us",
  "account": {
    "external_id": "3915522",
    "email": "casey@example.com",
    "display_name": "Casey Rivera"
  },
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:31:04Z"
}

Do not trust connection_id from the query string on its own. Anyone can type it. Fetch the connection server-side with your API key and confirm it belongs to the tenant whose session you are serving.

Connection statuses

Status	Meaning	What to do
`pending`	Created, consent not finished	Nothing. Once `connect_url` expires it cannot be completed.
`healthy`	Usable	Proceed.
`reauth_required`	Provider authorization lapsed beyond refresh	Run the connect flow again.
`revoked`	Unlinked, tokens deleted	Create a new connection.
`throttled`	Provider is rate limiting this account	Back off. It clears on its own.

Subscribe to connection.reauth_required and connection.revoked instead of polling.

Reconnecting

Reconnection is the same flow. Create a new connection for the same provider and account, and send the user through connect_url again. When the account matches an existing connection, the callback returns you to return_url carrying that existing connection_id—so links built on it keep working, with their ledgers and cursors intact. This is what you should offer when a connection goes reauth_required. Nothing re-imports.

Disconnecting

Endpoint

DELETE /connectors/v1/connections/{id}

cURL

curl -X DELETE https://api.case.dev/connectors/v1/connections/conn_abc123 \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

Tokens are revoked at the provider and deleted. Documents already imported into vaults stay where they are. To remove those documents too, add ?purge=true. The purge runs as a durable background workflow and returns 202 rather than 204.

purge=true deletes vault documents that this connection’s import links brought in. It is not reversible—confirm with the user before you call it.

Turning a provider off without disconnecting

Endpoint

PATCH /connectors/v1/connections

This stops new runs and scheduled syncs for one provider across the whole organization or installation. Credentials, links, and imported files are preserved, and runs already in flight are not interrupted. Because it is organization-wide, the body must include confirm_organization_wide: true.

Next steps

Import & Export

Browse the connected account and move files into a vault

Installations

Scope connections per customer tenant

Errors & Recovery

What each failure code means and which ones to retry

Get Started

Platform

Resources

Connect an Account

Step 1: Create the connection

return_url rules

Scope tiers

Step 2: Send the user to connect_url

Step 3: Handle the return

Connection statuses

Reconnecting

Disconnecting

Turning a provider off without disconnecting

Next steps

Import & Export

Installations

Errors & Recovery

​Step 1: Create the connection

​return_url rules

​Scope tiers

​Step 2: Send the user to connect_url

​Step 3: Handle the return

​Connection statuses

​Reconnecting

​Disconnecting

​Turning a provider off without disconnecting

​Next steps

Import & Export

Installations

Errors & Recovery

Step 1: Create the connection

return_url rules

Scope tiers

Step 2: Send the user to connect_url

Step 3: Handle the return

Connection statuses

Reconnecting

Disconnecting

Turning a provider off without disconnecting

Next steps