--- title: "Start connector connection" method: POST path: "/api/apps/{app_id}/external-auth/initiate" --- # Start connector connection `POST /api/apps/{app_id}/external-auth/initiate` ## Request - Base URL: `https://app.base44.com` - URL: `https://app.base44.com/api/apps/{app_id}/external-auth/initiate` - Auth: HTTP bearer This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production. Starts connecting a third-party account to the app with OAuth, and returns a link where a person signs in to the provider and approves access. The connection is recorded as yours, whichever provider account approves it. Connecting is done in steps: 1. Call this endpoint and open `redirect_url` in a browser. 2. Sign in to the provider and approve the requested scopes. This has to happen within five minutes of the call, and the link itself stops working after 10 minutes. 3. Poll [Get connector connection status](/api-reference/get-connector-connection-status) with the returned `connection_id` until it's `ACTIVE` or `FAILED`. Treat `redirect_url` as a credential. Whoever approves access through it connects their provider account to the app. A successful call doesn't always start an authorization. Read `already_authorized` and `error` first. When the app already has a working connection that covers the scopes, there's nothing to open. When another collaborator's account is connected, the call reports `different_user`. With `integration_type`, send `force_reconnect` to replace it with yours. Retrying starts a new authorization with a new link rather than returning the earlier one, so open the link from the latest response. Send `integration_type` to connect through Base44's OAuth app, or `connector_id` for a workspace connector that uses the workspace's own OAuth app. The call is refused when the workspace has turned off builder connections for the connector, and connectors with an `auth_method` of `platform_credentials` can't be connected this way. This is limited to 15 requests a minute per caller. Some workspaces have a different limit. This endpoint accepts a personal API key belonging to a user with editor access to the app. A read-only key is refused, and workspace API keys are not accepted. ## Path parameters - `app_id` string, required: ID of the app. ## Request body - InitiateConnectionRequest - `integration_type` union: Connector to connect through Base44's OAuth app, from `integration_type` in [List connectors](/api-reference/list-connectors). Send this or `connector_id`, not both. - '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 - `scopes` string[], nullable: OAuth scopes to ask the provider for. Scopes the app's current connection already has are kept unless `force_reconnect` is `true`. Defaults to an empty list, which asks for the connector's default scopes. - `force_reconnect` boolean: Whether to start a new authorization even when the app already has a working connection that covers the scopes. Send `true` to switch to another account. Applies only with `integration_type`. Defaults to `false`. - `connection_config` object, nullable: Values the connector needs before authorization, keyed by the `name` of each field from [Get connector connection fields](/api-reference/get-connector-connection-fields). Leave it out for connectors that have no fields. - `connector_id` string, nullable: ID of a workspace connector that uses the workspace's own OAuth app, set up in the workspace settings. Send this or `integration_type`, not both. - `notify_chat_on_success` boolean: Whether a successful connection adds a message to the app's AI chat so the AI picks up wiring the connector into the app. Applies only with `integration_type`. Defaults to `false`. ## Response `200` The authorization was started, or the response says why none was needed. - InitiateConnectionResponse: The start of a connector authorization, or why none was needed. - `redirect_url` string, nullable, required: Link to open in a browser so the user can sign in to the provider and approve access. It expires after 10 minutes. Treat it as a credential. The value is `null` when no authorization was started. - `connection_id` string, nullable, required: ID of the connection being authorized. Pass it to [Get connector connection status](/api-reference/get-connector-connection-status). When `already_authorized` is `true` it's the existing connection, or `null` if you sent `connector_id`. The value is `null` when `error` is set. - `integration_type` union: Connector being connected. Without `connector_id`, the value is `null` when `already_authorized` is `true` or `error` is set. - '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 - `already_authorized` boolean: Whether the app already has a working connection that covers the requested scopes (`true`), so there's nothing to open, or not (`false`). - `error` string, nullable: Why no authorization was started, or `null` if one was. Either `different_user`, when another collaborator's account is already connected (with `integration_type`, send `force_reconnect` to replace it), or `service_unavailable`, when the provider can't be reached. Retry later. - `error_message` string, nullable: Readable explanation of `error`, or `null` when `error` is `null`. ## Other responses - `400`: Both or neither of `integration_type` and `connector_id` were sent, a `connection_config` value is missing or invalid, the connector can't be connected this way, or `connector_id` isn't a connector in the app's workspace. - `401`: Missing or invalid credentials. - `402`: The app's workspace plan doesn't include connectors. - `403`: You don't have editor access to this app, you're a viewer in its workspace, your API key is read-only, or you used a workspace API key. Also returned when the workspace has turned off builder connections for the connector. - `404`: App not found, or the connector isn't available to you. - `409`: The app's store already uses this provider, so its connector can't also be connected, or the app's workspace requires an unlocked SSO session. - `422`: The body isn't a JSON object, or a field has the wrong type or format. - `429`: Rate limit reached. Retry later. ## Changes - **2026-10-11** `80287813ab84`: 1 info - the endpoint scheme security `PersonalAccessTokenAuth` was added to the API - **2026-09-30** `63675fa5257c`: 1 info - endpoint added [Operation history](https://skmtc.dev/base44/apis/base44-app-management-api/changes/api/apps/:app_id/external-auth/initiate/post.md) --- [API](https://skmtc.dev/base44/apis/base44-app-management-api.md) - [All operations](https://skmtc.dev/base44/apis/base44-app-management-api/llms.txt) - [OpenAPI document](https://skmtc.dev/base44/apis/base44-app-management-api/revisions/c534f09cf314?raw)