> ## 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.

# connectors

***

## Overview

Connectors module for managing OAuth tokens for external services.

Unlike the [integrations](../type-aliases/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](#shared-connectors):** A single OAuth token shared by all app users. Best for shared service accounts.
* **[App user connectors](#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.

Shared connectors come in two forms, depending on how the connector is set up. Both return the same app-wide token, so they differ only in how you identify the connector in code:

* **Platform connectors** are connected from the app's Integration settings or with the [`connectors push`](/developers/references/cli/commands/connectors-push) CLI command, and are identified by an [integration type](#available-connectors) string. Retrieve them with [`getConnection()`](#getconnection).
* **Workspace-registered connectors** are backed by your own OAuth app, registered once in Workspace Settings and consented to by the app builder. They are identified by a connector ID instead of an integration type. Retrieve them with [`getWorkspaceConnection()`](#getworkspaceconnection). Connectors whose OAuth app is specific to your own account, such as Databricks and Snowflake, work this way.

To use a shared connector, call the matching method on the service role client `base44.asServiceRole.connectors` from a backend function, then 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, that you need to build 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()](#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()`](#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

The connectors below can be used as shared connectors or as app user connectors. For a shared platform connector, pass the integration type string to [`getConnection()`](#getconnection). For a connector you register in Workspace Settings with your own OAuth app, use the connector ID with [`getWorkspaceConnection()`](#getworkspaceconnection) for a shared token, or with [`getCurrentAppUserConnection()`](#getcurrentappuserconnection) for a per-user token.

| Service               | Type identifier         |
| --------------------- | ----------------------- |
| Airtable              | `airtable`              |
| BambooHR              | `bamboohr`              |
| Box                   | `box`                   |
| Calendly              | `calendly`              |
| ClickUp               | `clickup`               |
| Contentful            | `contentful`            |
| Databricks            | `databricks`            |
| Discord               | `discord`               |
| Dropbox               | `dropbox`               |
| GitHub                | `github`                |
| GitLab                | `gitlab`                |
| Gmail                 | `gmail`                 |
| Google Ads            | `googleads`             |
| Google Analytics      | `google_analytics`      |
| Google BigQuery       | `googlebigquery`        |
| Google Calendar       | `googlecalendar`        |
| Google Classroom      | `google_classroom`      |
| Google Docs           | `googledocs`            |
| Google Drive          | `googledrive`           |
| Google Meet           | `googlemeet`            |
| Google Search Console | `google_search_console` |
| Google Sheets         | `googlesheets`          |
| Google Slides         | `googleslides`          |
| Google Tasks          | `googletasks`           |
| HubSpot               | `hubspot`               |
| Hugging Face          | `hugging_face`          |
| Instagram Business    | `instagram`             |
| Linear                | `linear`                |
| LinkedIn              | `linkedin`              |
| Microsoft Teams       | `microsoft_teams`       |
| Microsoft OneDrive    | `one_drive`             |
| Notion                | `notion`                |
| Outlook               | `outlook`               |
| QuickBooks            | `quickbooks`            |
| Salesforce            | `salesforce`            |
| SharePoint            | `share_point`           |
| Slack User            | `slack`                 |
| Slack Bot             | `slackbot`              |
| Snowflake             | `snowflake`             |
| Splitwise             | `splitwise`             |
| Square                | `square`                |
| Supabase              | `supabase`              |
| TikTok                | `tiktok`                |
| Typeform              | `typeform`              |
| Wix                   | `wix`                   |
| Wrike                 | `wrike`                 |

See the integration guides for more details:

* **Scopes and permissions**: [Gmail](https://docs.base44.com/Integrations/gmail-connector#gmail-scopes-and-permissions), [LinkedIn](https://docs.base44.com/Integrations/linkedin-connector#linkedin-scopes-and-permissions), [Slack](https://docs.base44.com/Integrations/slack-connector#slack-scopes-and-permissions), [GitHub](https://docs.base44.com/Integrations/github-connector#github-scopes-and-permissions)
* **Slack connector types**: [About the Slack connectors](https://docs.base44.com/Integrations/slack-connector#about-the-slack-connectors) explains the difference between `slack` and `slackbot`

### 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](#getconnection). See the [Dynamic Types](/developers/references/sdk/getting-started/dynamic-types) guide to get started.

## Methods

### ⚠️ getAccessToken()

<Danger>
  **Deprecated:** Use [getConnection](#getconnection) instead.
</Danger>

> **getAccessToken**(`integrationType`): `Promise`\<`string`>

Retrieves an OAuth access token for a specific [external integration type](#available-connectors).

#### Parameters

<ParamField body="integrationType" type="string" required>
  The type of integration, such as `'googlecalendar'`, `'slack'`, `'slackbot'`, `'github'`, or `'discord'`. See [Available connectors](#available-connectors) for the full list.
</ParamField>

#### Returns

`Promise<string>`

Promise resolving to the access token string.

#### Examples

<CodeGroup>
  ```typescript Google Calendar connection theme={null}
  // Get Google Calendar OAuth token and fetch upcoming events
  const googleToken = await base44.asServiceRole.connectors.getAccessToken('googlecalendar');

  // Fetch upcoming 10 events
  const timeMin = new Date().toISOString();
  const url = `https://www.googleapis.com/calendar/v3/calendars/primary/events?maxResults=10&orderBy=startTime&singleEvents=true&timeMin=${timeMin}`;

  const response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${googleToken}` }
  });

  const events = await response.json();
  ```

  ```typescript Slack User connection theme={null}
  // Get Slack user token and list channels
  const slackToken = await base44.asServiceRole.connectors.getAccessToken('slack');

  // List all public and private channels
  const url = 'https://slack.com/api/conversations.list?types=public_channel,private_channel&limit=100';

  const response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${slackToken}` }
  });

  const data = await response.json();
  ```

  ```typescript Slack Bot connection theme={null}
  // Get Slack bot token and post a message with a custom bot identity
  const botToken = await base44.asServiceRole.connectors.getAccessToken('slackbot');

  const response = await fetch('https://slack.com/api/chat.postMessage', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${botToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      channel: '#alerts',
      text: 'Deployment to production completed successfully.',
      username: 'Deploy Bot',
      icon_emoji: ':rocket:'
    })
  });

  const result = await response.json();
  ```
</CodeGroup>

***

### getConnection()

> **getConnection**(`integrationType`): `Promise`\<`ConnectorConnectionResponse`>

Retrieves the shared OAuth access token and connection configuration for a [shared connector](#shared-connectors) to a specific [external integration type](#available-connectors).

Use this when a single shared account is connected and all app users access the same token. For per-user tokens, use [`getCurrentAppUserConnection()`](#getcurrentappuserconnection) instead.

This form is for platform connectors identified by an integration type. Connectors backed by your own OAuth app registered in Workspace Settings, such as Databricks and Snowflake, are retrieved by connector ID with [`getWorkspaceConnection()`](#getworkspaceconnection) 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

<ParamField body="integrationType" type="string" required>
  The type of integration, such as `'googlecalendar'`, `'slack'`, `'slackbot'`, `'github'`, or `'discord'`. See [Available connectors](#available-connectors) for the full list.
</ParamField>

#### Returns

`ConnectorConnectionResponse`

Connection details.

<Accordion title="Properties">
  <ResponseField name="accessToken" type="string" required>
    The OAuth access token for the external service.
  </ResponseField>

  <ResponseField name="connectionConfig" type="Record<string, string> | null" required>
    Key-value configuration for the connection, or `null` if the connector does not provide one.
  </ResponseField>
</Accordion>

#### Examples

<CodeGroup>
  ```typescript Google Calendar connection theme={null}
  const { accessToken } = await base44.asServiceRole.connectors.getConnection('googlecalendar');

  const response = await fetch('https://www.googleapis.com/calendar/v3/users/me/calendarList', {
    headers: { Authorization: `Bearer ${accessToken}` }
  });

  const { items } = await response.json();
  ```

  ```typescript Slack connection theme={null}
  // Get Slack OAuth token and list channels
  const { accessToken } = await base44.asServiceRole.connectors.getConnection('slack');

  const url = 'https://slack.com/api/conversations.list?types=public_channel,private_channel&limit=100';

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${accessToken}` }
  });

  const data = await response.json();
  ```

  ```typescript Using connectionConfig theme={null}
  // Some connectors return a subdomain or other params needed to build the API URL
  const { accessToken, connectionConfig } = await base44.asServiceRole.connectors.getConnection('myservice');

  const subdomain = connectionConfig?.subdomain;
  const response = await fetch(
    `https://${subdomain}.example.com/api/v1/resources`,
    { headers: { Authorization: `Bearer ${accessToken}` } }
  );

  const data = await response.json();
  ```
</CodeGroup>

***

### getWorkspaceConnection()

> **getWorkspaceConnection**(`connectorId`): `Promise`\<`ConnectorConnectionResponse`>

Retrieves the shared OAuth access token and connection configuration for a [workspace-registered connector](#shared-connectors).

Use this for a connector backed by your own OAuth app that you register in Workspace Settings, such as Databricks or Snowflake. The app builder consents to the connector once, and the returned token is shared across all app users of the app. This is the shared-token counterpart to [`getCurrentAppUserConnection()`](#getcurrentappuserconnection), which returns a per-user token for the same kind of connector. The semantics match [`getConnection()`](#getconnection), except that you identify the connector by ID rather than by integration type.

Some connectors require connection-specific parameters to build API calls. In such cases, the returned `connectionConfig` is an object with those parameters, such as the account subdomain used to construct the API URL. When no extra parameters are needed, `connectionConfig` is `null`.

#### Parameters

<ParamField body="connectorId" type="string" required>
  The ID of the workspace connector, not the integration type string. You can find it on the connector's settings page in Workspace Settings.
</ParamField>

#### Returns

`ConnectorConnectionResponse`

Connection details.

<Accordion title="Properties">
  <ResponseField name="accessToken" type="string" required>
    The OAuth access token for the external service.
  </ResponseField>

  <ResponseField name="connectionConfig" type="Record<string, string> | null" required>
    Key-value configuration for the connection, or `null` if the connector does not provide one.
  </ResponseField>
</Accordion>

#### Example

<CodeGroup>
  ```typescript Snowflake connection theme={null}
  // Retrieve the shared token and run a statement against the account
  const { accessToken, connectionConfig } = await base44.asServiceRole.connectors.getWorkspaceConnection('abc123def');

  const response = await fetch(
    `https://${connectionConfig?.subdomain}.snowflakecomputing.com/api/v2/statements`,
    { headers: { Authorization: `Bearer ${accessToken}` } }
  );

  const data = await response.json();
  ```
</CodeGroup>

***

### getCurrentAppUserConnection()

> **getCurrentAppUserConnection**(`connectorId`): `Promise`\<`AppUserConnectorConnectionResponse`>

Retrieves the OAuth access token and connection configuration for an [app user connector](#app-user-connectors).

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()`](../functions/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()](#connectappuser).

#### Parameters

<ParamField body="connectorId" type="string" required>
  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.
</ParamField>

#### Returns

`AppUserConnectorConnectionResponse`

Connection details for an app user connector.

<Accordion title="Properties">
  <ResponseField name="accessToken" type="string" required>
    The OAuth access token for the app user's connection.
  </ResponseField>

  <ResponseField name="connectionConfig" type="Record<string, string> | null" required>
    Key-value configuration for the connection, or `null` if the connector does not provide one.
  </ResponseField>
</Accordion>

#### Examples

<CodeGroup>
  ```typescript Basic usage theme={null}
  const { accessToken } = await base44.asServiceRole.connectors.getCurrentAppUserConnection('abc123def');

  const response = await fetch('https://www.googleapis.com/calendar/v3/calendars/primary/events', {
    headers: { Authorization: `Bearer ${accessToken}` }
  });

  const data = await response.json();
  ```

  ```typescript Using connectionConfig theme={null}
  const { accessToken, connectionConfig } = await base44.asServiceRole.connectors.getCurrentAppUserConnection('abc123def');

  const subdomain = connectionConfig?.subdomain;
  const response = await fetch(
    `https://${subdomain}.example.com/api/v1/resources`,
    { headers: { Authorization: `Bearer ${accessToken}` } }
  );

  const data = await response.json();
  ```
</CodeGroup>

### connectAppUser()

> **connectAppUser**(`connectorId`): `Promise`\<`string`>

Initiates the OAuth flow for an [app user connector](#app-user-connectors).

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

<ParamField body="connectorId" type="string" required>
  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.
</ParamField>

#### Returns

`Promise<string>`

Promise resolving to the redirect URL string.

#### Example

<CodeGroup>
  ```typescript Start OAuth for the app user theme={null}
  const redirectUrl = await base44.connectors.connectAppUser('abc123def');

  // Redirect the user to the OAuth provider
  window.location.href = redirectUrl;
  ```
</CodeGroup>

***

### disconnectAppUser()

> **disconnectAppUser**(`connectorId`): `Promise`\<`void`>

Disconnects an app user's OAuth connection for an [app user connector](#app-user-connectors).

Removes the stored OAuth credentials for the currently authenticated app user's
connection to the specified connector.

#### Parameters

<ParamField body="connectorId" type="string" required>
  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.
</ParamField>

#### Returns

`Promise<void>`

Promise resolving when the connection has been removed.

#### Example

<CodeGroup>
  ```typescript Disconnect the app user's connection theme={null}
  await base44.connectors.disconnectAppUser('abc123def');
  ```
</CodeGroup>

## Type Definitions

### ConnectorIntegrationType

***

> **ConnectorIntegrationType** = keyof `ConnectorIntegrationTypeRegistry` *extends* `never` ? `string` : keyof `ConnectorIntegrationTypeRegistry`

Union of all connector integration type names from the [`ConnectorIntegrationTypeRegistry`](#connectorintegrationtyperegistry). Defaults to `string` when no types have been generated.

#### Example

<CodeGroup>
  ```typescript Using generated connector type names theme={null}
  // With generated types, you get autocomplete on integration types
  const connection = await base44.asServiceRole.connectors.getConnection('googlecalendar');
  const token = connection.accessToken;
  ```
</CodeGroup>

### ConnectorIntegrationTypeRegistry

***

Registry of connector integration type names. The [`types generate`](/developers/references/cli/commands/types-generate) command fills this registry, then [`ConnectorIntegrationType`](#connectorintegrationtype) resolves to a union of the keys.