---
title: "Create a connector"
method: POST
path: "/connectors"
tags: ["connectors"]
---

# Create a connector

`POST /connectors`

Create a connector for a provider and store its credentials.

## Request body

- HandlerConnectorCreateReq
  - `auth_type` string — Authentication method for the provider connection (e.g. `api_token`, `oauth`).
  - `collection` string — Default collection partition for synced objects. Deprecated alias: `sub_tenant_id`.
  - `credentials` object — Provider-specific credentials (typically `{"api_token": "..."}` or `{"access_token": "..."}`).
  - `database` string — Database/Collection are the canonical v2 names; TenantID/SubTenantID are their deprecated aliases, reconciled by the TenantAliases middleware before binding so TenantID is always populated. Neither is marked binding:required (mirroring TenantCreateRequest): a caller may send either spelling, and the tenant scope is validated downstream by resolveTenant. Requiring tenant_id here would force the generated SDK to demand the deprecated field.
  - `deployment_id` string — Internal deployment context for this connector.
  - `name` string — Human-readable label for this connector.
  - `plan` string — Subscription plan this connector runs under.
  - `provider` string, required — External provider being synced (e.g. `slack`, `github`, `linear`, `notion`, `gmail`).
  - `provider_account_scope` string — Identifier for the external account (e.g. Slack workspace ID, GitHub org name). Must be distinct across connectors for the same provider.
  - `sub_tenant_id` string — deprecated: use collection
  - `sync_engine` string — SyncEngine selects the sync pipeline: "classic" (default) or "moveit".
  - `sync_interval_seconds` integer — How frequently the scheduler triggers incremental syncs, in seconds.
  - `tenant_id` string — deprecated: use database

## Response `201`

Created

- ConnectorsConnector
  - `auth_type` string — Authentication method for the provider connection (e.g. `api_token`, `oauth`).
  - `collection` string — Default collection partition for synced objects. Canonical name; mirrors the deprecated `sub_tenant_id` alias.
  - `connector_id` string — Connector this resource belongs to.
  - `credential_ref` string — Internal reference to the stored credential record.
  - `database` string — Database/Collection are the canonical v2 names for the deprecated tenant_id/sub_tenant_id wire fields. They mirror the same values so a v2 client sees the canonical names on responses while a legacy client keeps reading tenant_id/sub_tenant_id. Not persisted (dynamodbav:"-"): the store builds items from tenant_id/sub_tenant_id and mirrors these on load. They are populated at every construction point (toConnector, connectorFromItem) rather than via MarshalJSON so Temporal's JSON data converter round-trips Connector activity inputs without spuriously populating them.
  - `deployment_id` string — Internal deployment context for this connector.
  - `last_attempted_sync_at` string — RFC3339 timestamp of the most recent sync attempt (successful or not).
  - `last_error` string — Error message from the most recent failed sync, empty string when no error.
  - `last_successful_sync_at` string — RFC3339 timestamp of the last successful sync completion.
  - `name` string — Human-readable label for this connector.
  - `next_sync_at` string — RFC3339 timestamp when the next scheduled sync will run.
  - `org_id` string — Organization that owns this resource.
  - `plan` string — Subscription plan this connector runs under.
  - `provider` string — External provider being synced (e.g. `slack`, `github`, `linear`, `notion`, `gmail`).
  - `provider_account_scope` string — Identifier for the external account (e.g. Slack workspace ID, GitHub org name). Must be distinct across connectors for the same provider.
  - `status` string — Lifecycle status of the connector (e.g. `active`, `paused`, `error`).
  - `sub_tenant_id` string — Default collection partition for synced objects. Deprecated — use `collection`.
  - `sync_engine` string — SyncEngine is "classic" (default, empty treated as classic) or "moveit". See the SyncEngine* constants; the scheduler branches on it.
  - `sync_interval_seconds` integer — How frequently the scheduler triggers incremental syncs, in seconds.
  - `sync_status` string — Current sync operation state (e.g. `idle`, `running`).
  - `tenant_id` string — Database that receives synced data. Deprecated — use `database`.
  - `user_id` string — User that created or owns this resource.

## Other responses

- `400` — Bad Request
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.net/hydradb/apis/hydradb-application-api.md) · [All operations](https://skmtc.net/hydradb/apis/hydradb-application-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hydradb/hydradb-application-api/versions/c773cb4e113a/schema)