メインコンテンツへスキップ

Overview

Connectors module for managing OAuth tokens for external services. Unlike the integrations module that provides pre-built functions, connectors give you raw OAuth tokens so you can call external service APIs directly. Use this when you need custom API interactions that the pre-built integrations do not cover. There are two connector types, depending on whether the token is shared across the app or specific to each user:
  • Shared connectors: A single OAuth token shared by all app users. Best for shared service accounts.
  • App user connectors: Each app user has their own OAuth token. Best for actions that need to happen as the individual user.

Shared connectors

All app users share a single OAuth token. Use this for shared accounts. For example, posting to a company Slack channel or reading from a shared Google Calendar. To use a shared connector:
  1. Connect the external service account in the app’s Integration settings or using the connectors push CLI command.
  2. In a backend function, call getConnection() using the service role client (base44.asServiceRole.connectors) with an integration type string to retrieve the shared OAuth token.
  3. Use the returned accessToken to call the external service’s API directly. Some connectors also return a connectionConfig with additional values such as a subdomain for building the API URL.

App user connectors

Each signed-in app user has their own OAuth token. Use this when each user needs to act as themselves. For example, sending emails from their Gmail account or posting to their personal LinkedIn. To use an app user connector:
  1. Register OAuth credentials for the service in Workspace Settings to get a connector ID. This requires workspace admin access.
  2. From the frontend, call connectAppUser() with the connector ID to get an authorization URL, then redirect the app user to that URL to complete the OAuth flow.
  3. In a backend function, call getCurrentAppUserConnection() using the service role client (base44.asServiceRole.connectors) with the connector ID to retrieve the app user’s token.
  4. Use the returned accessToken to call the external service’s API directly. Some connectors also return a connectionConfig with additional values such as a subdomain for building the API URL.

Available connectors

All connectors listed below support both shared and app user connections. For shared connectors, pass the integration type string to getConnection(). For app user connectors, register the connector in Workspace Settings and use the connector ID with getCurrentAppUserConnection(). See the integration guides for more details:

Dynamic Types

If you’re working in a TypeScript project, you can generate types from your app’s connector configurations to get autocomplete on integration type names when calling getConnection. See the Dynamic Types guide to get started.

Methods

⚠️ getAccessToken()

Deprecated: Use getConnection instead.
getAccessToken(integrationType): Promise<string>
Retrieves an OAuth access token for a specific external integration type.

Parameters

integrationType
string
必須
The type of integration, such as 'googlecalendar', 'slack', 'slackbot', 'github', or 'discord'. See Available connectors for the full list.

Returns

Promise<string> Promise resolving to the access token string.

Examples


getConnection()

getConnection(integrationType): Promise<ConnectorConnectionResponse>
Retrieves the shared OAuth access token and connection configuration for a shared connector to a specific external integration type. Use this when a single shared account is connected and all app users access the same token. For per-user tokens, use getCurrentAppUserConnection() instead. Some connectors require connection-specific parameters to build API calls. In such cases, the returned connectionConfig is an object with the additional parameters. If there are no extra parameters needed for the connection, the connectionConfig is null. For example, a service might need a subdomain to construct the API URL in the form of {subdomain}.example.com. In such a case the subdomain will be available as a property of the connectionConfig object.

Parameters

integrationType
string
必須
The type of integration, such as 'googlecalendar', 'slack', 'slackbot', 'github', or 'discord'. See Available connectors for the full list.

Returns

ConnectorConnectionResponse Connection details.
accessToken
string
必須
The OAuth access token for the external service.
connectionConfig
Record<string, string> | null
必須
Key-value configuration for the connection, or null if the connector does not provide one.

Examples


getCurrentAppUserConnection()

getCurrentAppUserConnection(connectorId): Promise<AppUserConnectorConnectionResponse>
Retrieves the OAuth access token and connection configuration for an app user connector. The token returned is specific to the app user making the current request. For this to work, the SDK client must know which app user to act on behalf of. Use createClientFromRequest() in a Base44 backend function to create such a client. It reads the app user’s JWT from the incoming request and attaches it automatically so the runtime can resolve the correct user’s connection. The connector must be registered in Workspace Settings with OAuth credentials before this method can return a connection. The app user must also have completed the OAuth flow using connectAppUser().

Parameters

connectorId
string
必須
The ID of the app user connector configured in your workspace. This is not the integration type string. You can find it on the connector’s settings page in Workspace Settings.

Returns

AppUserConnectorConnectionResponse Connection details for an app user connector.
accessToken
string
必須
The OAuth access token for the app user’s connection.
connectionConfig
Record<string, string> | null
必須
Key-value configuration for the connection, or null if the connector does not provide one.

Examples

connectAppUser()

connectAppUser(connectorId): Promise<string>
Initiates the OAuth flow for an app user connector. Returns a redirect URL that the app user should be navigated to in order to authenticate with the external service. The scopes and integration type are derived from the connector configuration in the backend.

Parameters

connectorId
string
必須
The ID of the app user connector configured in your workspace. The AI builder inserts this ID into generated code when it sets up the connector flow. You can also retrieve it from the workspace connectors API.

Returns

Promise<string> Promise resolving to the redirect URL string.

Example


disconnectAppUser()

disconnectAppUser(connectorId): Promise<void>
Disconnects an app user’s OAuth connection for an app user connector. Removes the stored OAuth credentials for the currently authenticated app user’s connection to the specified connector.

Parameters

connectorId
string
必須
The ID of the app user connector configured in your workspace. The AI builder inserts this ID into generated code when it sets up the connector flow. You can also retrieve it from the workspace connectors API.

Returns

Promise<void> Promise resolving when the connection has been removed.

Example

Type Definitions

ConnectorIntegrationType


ConnectorIntegrationType = keyof ConnectorIntegrationTypeRegistry extends never ? string : keyof ConnectorIntegrationTypeRegistry
Union of all connector integration type names from the ConnectorIntegrationTypeRegistry. Defaults to string when no types have been generated.

Example

ConnectorIntegrationTypeRegistry


Registry of connector integration type names. The types generate command fills this registry, then ConnectorIntegrationType resolves to a union of the keys.