---
title: "Create workspace connector"
method: POST
path: "/api/workspace/{workspace_id}/connectors"
---

# Create workspace connector

`POST /api/workspace/{workspace_id}/connectors`

## Request

- Base URL: `https://app.base44.com`
- URL: `https://app.base44.com/api/workspace/{workspace_id}/connectors`
- Auth: HTTP bearer

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Creates a workspace connector.

A workspace connector holds the workspace's own OAuth app for a connector, so the workspace's apps connect through it instead of through Base44's OAuth app. A connector can also run on Base44's OAuth app for the apps' users, when `credential_source` is `base44`.

With `credential_source` set to `byo`, send the client ID and secret of an OAuth app you registered in the provider's console, then register the redirect URIs from [Get OAuth redirect URIs](/api-reference/get-oauth-redirect-uris) there too. With `base44`, send neither: the connector runs on Base44's OAuth app, which needs a plan that includes Base44-managed connectors and accepts only the scopes that app is approved for.

Names are unique in a workspace, so retrying a create that succeeded returns a `409`.

This is limited to 30 requests per minute, shared by [Create workspace connector](/api-reference/create-workspace-connector), [Update workspace connector](/api-reference/update-workspace-connector), and [Delete workspace connector](/api-reference/delete-workspace-connector). A signed-in session has its own limit, and every personal access token for the workspace shares one. Some workspaces have a different limit.

<Note>Call this as an owner or admin of the workspace, with a personal access token for that workspace sent as a Bearer token, or from a signed-in session. A read-only token is refused. Workspace API keys aren't accepted.</Note>

## Path parameters

- `workspace_id` string, required: ID of the workspace. With a personal access token, use the token's workspace. Get it from `organization_id` in [Get app](/api-reference/get-app).

## Request body

- CreateOrganizationConnectorRequest: A workspace connector to create.
  - `integration_type` union, required: Connector to create it for, from `integration_type` in [List connectors](/api-reference/list-connectors). Its `connector_mode` has to be one of `all`, `app_user_only`, `byo_shared_only`, or `byo_shared_and_app_user`.
    - 'googlecalendar' | 'google_classroom' | 'googledrive' | 'gmail' | 'googlesheets' | 'googledocs' | 'googleslides' | 'googlebigquery' | 'googlemeet' | 'googletasks' | 'googleads' | 'google_analytics' | 'google_search_console' | 'slack' | 'notion' | 'salesforce' | 'hubspot' | 'linkedin' | 'tiktok' | 'instagram' | 'discord' | 'slackbot' | 'wix' | 'github' | 'gitlab' | 'bamboohr' | 'dropbox' | 'clickup' | 'wrike' | 'box' | 'outlook' | 'linear' | 'airtable' | 'microsoft_teams' | 'share_point' | 'one_drive' | 'typeform' | 'splitwise' | 'hugging_face' | 'calendly' | 'contentful' | 'supabase' | 'snowflake' | 'databricks' | 'quickbooks' | 'square'
    - string
  - `name` string, required: Name of the workspace connector. Must be unique in the workspace, matching case exactly.
  - `credential_source` 'byo' | 'base44': Whose OAuth app the connector runs on: `byo` for your own, registered in the provider's console, or `base44` for Base44's. Defaults to `byo`. `base44` needs a plan that includes Base44-managed connectors, and only some connectors offer it.
  - `client_id` string: Client ID of your OAuth app, up to 512 characters. Required with `byo`. Leave it out with `base44`.
  - `client_secret` string: Client secret of your OAuth app, up to 512 characters. Required with `byo`, except for connectors whose OAuth apps have no secret, such as Linear. Leave it out with `base44`. It's stored encrypted and never returned.
  - `scopes` string[]: OAuth scopes connections through this connector ask for. With `base44`, only scopes Base44's OAuth app is approved for are accepted.
  - `connection_config` object: Values the connector needs, keyed by the `name` of each of its connection fields. Leave it out for connectors that have none.

## Response `201`

The new workspace connector.

- OrganizationConnectorResponse: A workspace connector. The client secret is never returned.
  - `id` string, required: ID of the workspace connector. Pass it as `connector_id` to [Start connector connection](/api-reference/start-connector-connection).
  - `organization_id` string, required: ID of the workspace.
  - `integration_type` string, required: Connector it's for.
  - `name` string, required: Name of the workspace connector.
  - `credential_source` 'byo' | 'base44': Whose OAuth app it runs on: `byo` for the workspace's own, or `base44` for Base44's.
  - `client_id` string, required: Client ID of the workspace's OAuth app. Empty for a connector on Base44's OAuth app.
  - `scopes` string[], required: OAuth scopes connections through it ask for.
  - `connection_config` object: Connection values saved on it, keyed by field name. Empty when the connector needs none.
  - `uses_oauth_gateway` boolean: Whether new connections return to the single gateway redirect URI (`true`) or to the per-app ones (`false`). [Get OAuth redirect URIs](/api-reference/get-oauth-redirect-uris) says which to register.

## Other responses

- `400`: The connector can't be set up as a workspace connector, `client_secret` is missing for a connector that needs one, the connector has no Base44-managed option, a scope isn't available on Base44's OAuth app, or a `connection_config` value is missing or invalid.
- `401`: Missing or invalid credentials.
- `402`: `credential_source` is `base44` and the workspace's plan doesn't include Base44-managed connectors.
- `403`: You aren't an owner or admin of the workspace, your token is for a different workspace or is read-only, or your credential can't be used on this endpoint.
- `404`: The connector isn't available to you.
- `409`: Another connector in the workspace has this name, or the workspace requires an unlocked SSO session.
- `422`: A field has the wrong type or format, `client_id` is missing with `byo`, or `client_id` or `client_secret` was sent with `base44`.
- `429`: Rate limit exceeded.

## Changes

> 58 revisions in range; 1 not diffed.

- **2026-10-12** `5e139db2e643`: 1 info
  - the endpoint scheme security `PersonalAccessTokenAuth` was added to the API
- **2026-10-09** `fc604cdcc3a2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/adexad/apis/base44-app-management-api/changes/api/workspace/:workspace_id/connectors/post.md)

---

[API](https://skmtc.dev/adexad/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/adexad/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adexad/apis/base44-app-management-api/revisions/fa29e915c226?raw)