# Create a connection

> 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.

Source: https://docs.stacksync.com/api-reference/connections/create_connection

`POST https://api.stacksync.com/v1/workspaces/{workspace_id}/connections`

- Operation: `create_connection`
- Resource: Connections
- Access: writes data

## Authentication

- `Authorization: Bearer <key>`: A workspace API key (workspace_…, created by a workspace owner under Workspace settings > Stacksync API) acts with editor rights on that workspace only; a user API key (user_…, created under Profile > Stacksync API) acts as that user in every workspace they belong to. POST, PUT and PATCH requests must send Content-Type: application/json. Every authentication failure answers 403.
- `Content-Type: application/json` on every request with a body.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace_id` | integer | Yes | The workspace the resources belong to |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `region` | string (besg \| usnv) | Yes | Data region the connection is stored in |

## Request body

`application/json`. The connection to create

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_name` | string | Yes | The name of the connection, unique in the workspace |
| `is_shared_with_workspace` | boolean | Yes | True to let every editor of the workspace use the connection, false to keep it to the user of the API key |
| `app_type` | string (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) | Yes | The app to connect, as shown in Stacksync |
| `credentials` | object | Yes | 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. |

## Returns

### 200 The connection created

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object (ConnectionDetails) | Yes | A connection as the connection routes answer it |
| `data.connection_id` | string (uuid) | Yes | The connection |
| `data.connection_name` | string | Yes | The name of the connection, unique in the workspace |
| `data.app_type` | string | Yes | The app the connection is for, as shown in Stacksync (for example `postgres`, `salesforce`, `supabase`) |
| `data.is_shared_with_workspace` | boolean | Yes | Whether every editor of the workspace can use the connection, or only the user who created it |
| `data.created_time` | string | Yes | When the connection was created. Local server time as `YYYY-MM-DD HH:MM:SS` (UTC) |
| `data.last_modified_time` | string | Yes | When the connection was last changed. Local server time as `YYYY-MM-DD HH:MM:SS` (UTC) |
| `data.credentials_options` | object | Yes | 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. |

## Example request

```bash
curl -X POST "https://api.stacksync.com/v1/workspaces/{workspace_id}/connections?region=besg" \
  -H "Authorization: Bearer $STACKSYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "connection_name": "Production Postgres",
  "is_shared_with_workspace": true,
  "app_type": "postgres",
  "credentials": {
    "connection_string": "postgresql://sync_user:********@db.example.com:5432/crm",
    "schema": "public"
  }
}'
```

`db.example.com` is a placeholder: replace it with your own host, which the API checks before saving (the example as written is refused).

## Example response (200)

```json
{
  "data": {
    "connection_id": "9b2e4f60-1c3d-4a5e-8f70-2d4c6e8a0b12",
    "connection_name": "Production Postgres",
    "app_type": "postgres",
    "is_shared_with_workspace": true,
    "created_time": "2026-10-01 09:12:44",
    "last_modified_time": "2026-10-01 09:12:44",
    "credentials_options": {
      "uses_ssh_tunnel": false,
      "connection_mode": "direct"
    }
  }
}
```

## Errors

| Status | Meaning | Body |
| --- | --- | --- |
| 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`) | `{ "error": string }` |
| 403 | Forbidden: invalid API key, API key of another workspace, insufficient scope, workspace unavailable, or a non-GET request without `Content-Type: application/json` | `{ "error": string }` |

## Related

- [API Reference overview](https://docs.stacksync.com/api-reference): base URLs, regions, pagination, idempotency and errors
- [Authentication](https://docs.stacksync.com/api-reference/authentication): API keys and the 403 answers
- OpenAPI document: https://docs.stacksync.com/openapi.json
- [List connections](https://docs.stacksync.com/api-reference/connections/list_connections)
- [Get a connection](https://docs.stacksync.com/api-reference/connections/get_connection)
- [Update a connection](https://docs.stacksync.com/api-reference/connections/update_connection)
- [Delete a connection](https://docs.stacksync.com/api-reference/connections/delete_connection)
- [Reauthorize a connection](https://docs.stacksync.com/api-reference/connections/reauthorize_connection)