Skip to main content
A provider connection links a project to an account at a provider such as Vercel, AWS, or Cloudflare. Use this API to start the setup, check the state of a connection, repair it, or remove it. 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, planetscale, railway, render, sentry, and vercel.

​
Operations

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

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.
For Vercel and Railway, the URL opens the Squasher dashboard, which signs the person in and sends them to the provider. After consent, the person chooses the provider project on the Integrations page. 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.

​
Provider health and resources

GET .../provider-health returns one entry for each connected provider in providers. Each entry has the connection status, the worst freshness of its streams, and a streams list. Each stream has: An auth or permission error needs a new connection. GET .../provider-resources returns resources: the zones, Workers, databases, branches, and services that Squasher found. Each resource has provider, kind, name, parent_id, freshness, observed_at, a few key metrics (name, label, value, unit, window_seconds), and the OpenTelemetry resource attributes that join it to its telemetry. Use provider to list one provider.

​
Provider setup without a plan

  • POST .../provider-connections/planetscale takes organization, service_token_id, and service_token. Squasher checks the token, then returns the connection, the number of databases, and the webhook_url for deploy events. See PlanetScale.
  • PUT .../provider-connections/planetscale/webhook takes the webhook signing secret (8 to 512 characters) and returns configured and webhook_url.
  • PUT .../provider-connections/cloudflare/analytics takes enabled and returns enabled and the required_permissions of the pull. See Cloudflare analytics metrics.
  • GET .../cloudflare/accounts lists the accounts granted by OAuth. Pass the selected account_id to GET .../cloudflare/workers?account_id=..., then send that account and one or more worker_ids to POST .../cloudflare/provision.

​
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 the browser flow for GitHub, Linear, Slack, Railway, and Vercel, and returns to the CLI when it finishes. Use squasher integrations connect-plan for other interactive providers, then use the Cloudflare account and Worker commands to finish setup.
  • squasher integrations list, readiness, get, reconcile, and disconnect cover generic connection control. cloudflare-accounts, cloudflare-workers, and cloudflare-provision complete Cloudflare setup. Risky commands ask for confirmation unless --yes is supplied.
  • MCP exposes provider discovery, connection reads, readiness, provider health and resources, repair, disconnect, Cloudflare account and Worker selection, Cloudflare provisioning, and the analytics switch. Write, dangerous, and destructive operations still require the MCP session’s access and approval gates. Credential-bearing setup operations remain API or dashboard actions.
Provider consent remains a human browser action. MCP can manage an already-authorized connection with the same project scope and approval controls as the API. Related: One-click provider connections, Provider capabilities API.