---
title: "Create a connection"
method: POST
path: "/v1/workspaces/{workspace_id}/connections"
tags: ["Connections"]
---

# Create a connection

`POST /v1/workspaces/{workspace_id}/connections`

## Request

- Base URL: `https://api.stacksync.com`
- URL: `https://api.stacksync.com/v1/workspaces/{workspace_id}/connections`
- Auth: HTTP bearer

Create a connection to an app with the credentials given, after testing them against the app. Only the user of the API key can use the connection unless `is_shared_with_workspace` is true. Answers the connection without its secrets.

## Path parameters

- `workspace_id` integer, required

## Query parameters

- `region` 'besg' | 'usnv', required

## Request body

- CreateConnectionBody: The connection to create
  - `connection_name` string, required: The name of the connection, unique in the workspace
  - `is_shared_with_workspace` boolean, required: True to let every editor of the workspace use the connection, false to keep it to the user of the API key
  - `app_type` 'postgres' | 'postgres_heroku' | 'salesforce' | 'hubspot' | 'bigquery' | 'amazon_lightsail' | 'amazon_rds' | 'supabase' | 'supabase_oauth' | 'scaleway_postgres' | 'cockroachdb' | 'render_postgres' | 'google_alloydb' | 'snowflake' | 'dynamodb' | 'mongodb' | 'sap' | 'zendesk' | 'zoho_crm' | 'microsoft_dynamics' | 'dynamics365_crm' | 'dynamics365_finance' | 'dynamics365_business_central' | 'pipedrive' | 'marketo' | 'odoo' | 'airtable' | 'attio_crm' | 'motherduck' | 'shopify' | 'oracledb' | 'mysql' | 'mariadb' | 'sqlserver' | 'suiteanalytics' | 'twilio' | 'bamboohr' | 'sendgrid' | 'twenty_crm' | 'monday' | 'acumatica' | 'extensiv', required: The app to connect, as shown in Stacksync
  - `credentials` object, required: The credentials of the app, checked per app type before the connection is tested: `postgres`, `postgres_heroku`: `connection_string`, `schema`; `mongodb`: `connection_string`, `database`; `hubspot`, `monday`: `code` (the OAuth authorization code); `salesforce`: `code`, `account_type` (`standard` or `sandbox`); `sendgrid`, `twenty_crm`: `api_key`; `twilio`: `account_sid`, `auth_token`; `bamboohr`: `company_domain`, `api_key`; `snowflake`: `account`, `username`, `warehouse`; `suiteanalytics`: `account_id`, `consumer_key`, `consumer_secret`, `token_id`, `token_secret`, `role_id`; `bigquery`: `service_account_credentials` (the service account JSON: `type`, `project_id`, `private_key_id`, `private_key`, `client_email`, `client_id`, `auth_uri`, `token_uri`, `auth_provider_x509_cert_url`, `client_x509_cert_url`); `acumatica`: `instance_url`, `client_id`, `client_secret`, `code`, `redirect_uri`; `extensiv`: `client_id`, `client_secret`, optional `user_login_id` and `is_sandbox` (boolean). Other app types take the fields their connection form asks for; they are checked when the connection is tested.

## Response `200`

The connection created

- ConnectionDetailsResponse: The connection written
  - `data` ConnectionDetails, required: A connection as the connection routes answer it
    - `connection_id` string, uuid, required: The connection
    - `connection_name` string, required: The name of the connection, unique in the workspace
    - `app_type` string, required: The app the connection is for, as shown in Stacksync (for example `postgres`, `salesforce`, `supabase`)
    - `is_shared_with_workspace` boolean, required: Whether every editor of the workspace can use the connection, or only the user who created it
    - `created_time` string, required: When the connection was created. Local server time as `YYYY-MM-DD HH:MM:SS` (UTC)
    - `last_modified_time` string, required: When the connection was last changed. Local server time as `YYYY-MM-DD HH:MM:SS` (UTC)
    - `credentials_options` object, required: The non-secret settings of the connection. A database connection carries `uses_ssh_tunnel` (boolean) and `connection_mode` (`direct` or `ssh_tunnel`); a Salesforce connection carries `organization_id` and `instance_url`; a HubSpot connection carries its portal settings. Secrets are never answered.

## Other responses

- `400`: The `region` is missing or not one of besg, usnv; a required field is missing or of the wrong type; the app type is not supported; the credentials miss a field the app type needs; the app refused the credentials (`Error creating connection`)
- `403`: Forbidden: invalid API key, API key of another workspace, insufficient scope, workspace unavailable, or a non-GET request without `Content-Type: application/json`

---

[API](https://skmtc.dev/stacksync/apis/stacksync-api.md) - [All operations](https://skmtc.dev/stacksync/apis/stacksync-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stacksync/apis/stacksync-api/revisions/21f4ba4b214e?raw)