> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider connections API

> Create, inspect, repair, and remove project-scoped one-click provider connections.

Provider connection operations use the normal Squasher API-key authorization. The key must have
access to the project in the path. Write operations require project write access.

Supported provider IDs are `aws`, `cloudflare`, `gcp`, `notion`, `railway`, `render`, `sentry`, and
`vercel`.

## Operations

| Operation              | Method and path                                                               | Risk        |
| ---------------------- | ----------------------------------------------------------------------------- | ----------- |
| List connections       | `GET /v1/projects/{project_id}/provider-connections`                          | Read        |
| List runtime readiness | `GET /v1/projects/{project_id}/provider-connections/readiness`                | Read        |
| Get a connection       | `GET /v1/projects/{project_id}/provider-connections/{provider}`               | Read        |
| Create a setup plan    | `POST /v1/projects/{project_id}/provider-connections/{provider}/connect-plan` | Write       |
| Check and repair       | `POST /v1/projects/{project_id}/provider-connections/{provider}/reconcile`    | Dangerous   |
| Disconnect             | `DELETE /v1/projects/{project_id}/provider-connections/{provider}`            | Destructive |

For a Sentry installation with more than one project, the OAuth callback returns a short-lived,
sealed selection token to the dashboard. Use `POST /v1/projects/{project_id}/providers/sentry/selection-projects`
to list the server-verified choices, then use `POST /v1/projects/{project_id}/providers/sentry/select-project`
to complete setup. The token stays project-bound and expires; clients must not ask users to type a
project slug that the server did not list.

## Create a setup plan

```bash theme={null}
curl -X POST \
  "https://api.squasher.ai/v1/projects/$PROJECT_ID/provider-connections/vercel/connect-plan" \
  -H "x-squasher-key: $SQUASHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"return_url":"https://app.example.com/integrations"}'
```

The response contains one action:

* `oauth_redirect`: open the returned provider consent URL.
* `provider_installation`: open the returned provider-app installation URL.
* `cloudformation_launch`: open the AWS CloudFormation launch URL.
* `api_key_form`: collect the listed fields over a secure connection.

The setup URL can expire. Do not store it as a durable credential. Provider credentials stay on the
Squasher server and are not returned by list or get operations.

The API creates the plan; it does not complete provider consent. A person must open the returned URL,
sign in to the provider, review the scope, and approve the OAuth grant, app installation, or
CloudFormation stack. The provider callback then completes the connection. OAuth cannot run as a
non-interactive API-only flow.

Provider-specific `settings` can narrow the target, such as a provider project, Worker, service, or
environment. Use the matching provider guide for supported settings.

## Connection state

A connection can be `awaiting_authorization`, `provisioning`, `connected`, `reconnect_required`, or
`failed`. A successful response includes the provider, authorization mode, external account label,
status, last error, and update time. It does not include provider tokens.

## Repair and disconnect

Repair can create, update, or remove Squasher-owned resources at the provider. Call it only through
an explicit dashboard or authenticated API action. Disconnect removes the Squasher-owned remote
resources and revokes stored access when the provider supports revocation. It does not remove
unrelated provider resources.

## API, CLI, and MCP limits

* The public API exposes all operations in the table. OAuth and provider installations still require
  a person to complete the returned browser flow.
* `squasher integrations connect` opens a browser for the OAuth providers that the CLI lists as
  supported. The CLI does not provide non-interactive OAuth or generic one-click repair and
  disconnect commands. Use the dashboard for those actions.
* MCP exposes provider discovery, connection reads, and runtime readiness. An MCP agent can explain
  the state and prepare safe next steps, but it cannot call connect-plan, repair, or disconnect.

This boundary keeps provider consent and remote mutations out of autonomous agent execution.

Related: [One-click provider connections](/integrations/provider-connections), [Provider
capabilities API](/api-reference/provider-capabilities).