Sign in

Start connector connection

Changed on

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

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 with the returned connection_id until it's ACTIVE or FAILED.

<Warning>Treat redirect_url as a credential. Whoever approves access through it connects their provider account to the app.</Warning>

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.

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

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

Path parameters

app_idstring required

ID of the app.

Request body

scopesstring[] 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_reconnectboolean

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_configobject nullable

Values the connector needs before authorization, keyed by the name of each field from Get connector connection fields. Leave it out for connectors that have no fields.

connector_idstring 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_successboolean

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.

Example request

{
  "scopes": [
    "https://www.googleapis.com/auth/calendar.readonly"
  ],
  "connection_config": {
    "subdomain": "acme-prod"
  },
  "connector_id": "6820f3a4e7b91d003c45a1f9"
}

Response

The authorization was started, or the response says why none was needed.

redirect_urlstring 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_idstring nullable required

ID of the connection being authorized. Pass it to 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.

already_authorizedboolean

Whether the app already has a working connection that covers the requested scopes (true), so there's nothing to open, or not (false).

errorstring 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_messagestring nullable

Readable explanation of error, or null when error is null.

Example response

{
  "redirect_url": "https://app.base44.com/api/external-auth/connect/3f9c2a7e5b8d4c1fa6e0d2b7c9a1e4f3",
  "connection_id": "base44_6820f3a4e7b91d003c45a1f7",
  "error": "different_user",
  "error_message": "Integration googlecalendar is already authorized by a different user for this app."
}

Changes