> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Start connector connection
> 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.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/external-auth/initiate
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- PersonalAccessTokenAuth: []
paths:
/api/apps/{app_id}/external-auth/initiate:
post:
summary: Start connector connection
description: >-
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.
operationId: initiate_connection_api_apps__app_id__external_auth_initiate_post
parameters:
- name: app_id
in: path
required: true
schema:
type: string
description: ID of the app.
title: App Id
description: ID of the app.
example: 6820f3a4e7b91d003c45a1f2
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateConnectionRequest'
responses:
'200':
description: >-
The authorization was started, or the response says why none was
needed.
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateConnectionResponse'
'400':
description: >-
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':
description: Missing or invalid credentials.
'402':
description: The app's workspace plan doesn't include connectors.
'403':
description: >-
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':
description: App not found, or the connector isn't available to you.
'409':
description: >-
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':
description: >-
The body isn't a JSON object, or a field has the wrong type or
format.
'429':
description: Rate limit reached. Retry later.
components:
schemas:
InitiateConnectionRequest:
properties:
integration_type:
anyOf:
- type: string
enum:
- 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
- type: string
maxLength: 80
minLength: 1
pattern: ^[a-z0-9_]+$
- type: 'null'
title: Integration Type
description: >-
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.
example: googlecalendar
scopes:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Scopes
description: >-
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.
example:
- https://www.googleapis.com/auth/calendar.readonly
force_reconnect:
type: boolean
title: Force Reconnect
description: >-
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`.
default: false
example: false
connection_config:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Connection Config
description: >-
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.
example:
subdomain: acme-prod
connector_id:
anyOf:
- type: string
- type: 'null'
title: Connector Id
description: >-
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.
example: 6820f3a4e7b91d003c45a1f9
notify_chat_on_success:
type: boolean
title: Notify Chat On Success
description: >-
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`.
default: false
example: false
type: object
title: InitiateConnectionRequest
InitiateConnectionResponse:
properties:
redirect_url:
anyOf:
- type: string
- type: 'null'
title: Redirect Url
description: >-
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.
example: >-
https://app.base44.com/api/external-auth/connect/3f9c2a7e5b8d4c1fa6e0d2b7c9a1e4f3
connection_id:
anyOf:
- type: string
- type: 'null'
title: Connection Id
description: >-
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.
example: base44_6820f3a4e7b91d003c45a1f7
integration_type:
anyOf:
- type: string
enum:
- 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
- type: string
maxLength: 80
minLength: 1
pattern: ^[a-z0-9_]+$
- type: 'null'
title: Integration Type
description: >-
Connector being connected. Without `connector_id`, the value is
`null` when `already_authorized` is `true` or `error` is set.
example: googlecalendar
already_authorized:
type: boolean
title: Already Authorized
description: >-
Whether the app already has a working connection that covers the
requested scopes (`true`), so there's nothing to open, or not
(`false`).
default: false
example: false
error:
anyOf:
- type: string
- type: 'null'
title: Error
description: >-
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.
example: different_user
error_message:
anyOf:
- type: string
- type: 'null'
title: Error Message
description: Readable explanation of `error`, or `null` when `error` is `null`.
example: >-
Integration googlecalendar is already authorized by a different user
for this app.
type: object
required:
- redirect_url
- connection_id
title: InitiateConnectionResponse
description: The start of a connector authorization, or why none was needed.
securitySchemes:
PersonalAccessTokenAuth:
type: http
scheme: bearer
description: 'Personal access token, sent as `Authorization: Bearer `.'
````