> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suada.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Integration

> Initialize OAuth flow for an integration

Start the OAuth flow to connect a third-party integration.

## URL Parameters

<ParamField path="integrationType" type="string" required>
  The type of integration to connect. Valid values:

  * `google-analytics`
  * `notion`
  * `slack`
  * `zoho`
  * `gmail`
</ParamField>

## Request

<ParamField body="externalUserIdentifier" type="string" required>
  Unique identifier for the user in your system
</ParamField>

<ParamField body="passthroughRedirectUri" type="string" required>
  The URL to redirect to after OAuth completion
</ParamField>

<ParamField body="dc" type="string">
  Data center for Zoho integration (e.g., 'com', 'eu')
</ParamField>

<ParamField body="scopes" type="string[]">
  Additional OAuth scopes for Zoho integration
</ParamField>

## Response

<ResponseField name="authUrl" type="string">
  The OAuth authorization URL to redirect the user to
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://suada.ai/api/public/integrations/notion/connect \
    -H "Authorization: Bearer sk-suada-your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "externalUserIdentifier": "user-123",
      "passthroughRedirectUri": "https://your-app.com/oauth/callback"
    }'
  ```

  ```typescript TypeScript theme={null}
  import { Suada } from '@suada/node';

  const suada = new Suada({
    apiKey: 'your-api-key'
  });

  const { authUrl } = await suada.connectIntegration('notion', {
    externalUserIdentifier: 'user-123',
    passthroughRedirectUri: 'https://your-app.com/oauth/callback'
  });

  // Redirect user to authUrl
  window.location.href = authUrl;
  ```

  ```python Python theme={null}
  from suada import Suada, SuadaConfig

  suada = Suada(
      config=SuadaConfig(
          api_key="your-api-key"
      )
  )

  result = suada.connect_integration(
      integration_type="notion",
      external_user_identifier="user-123",
      passthrough_redirect_uri="https://your-app.com/oauth/callback"
  )

  # Redirect user to result.auth_url
  ```
</CodeGroup>

<ResponseExample>
  ```json theme={null}
  {
    "authUrl": "https://api.notion.com/v1/oauth/authorize?client_id=..."
  }
  ```
</ResponseExample>

## Integration-Specific Parameters

### Google Analytics

No additional parameters required.

### Notion

No additional parameters required.

### Slack

No additional parameters required.

### Zoho

<ParamField body="dc" type="string" default="com">
  Zoho data center:

  * `com` - US data center
  * `eu` - EU data center
  * `in` - India data center
  * `com.cn` - China data center
  * `com.au` - Australia data center
</ParamField>

<ParamField body="scopes" type="string[]">
  List of Zoho API scopes to request. Default scopes include:

  * `ZohoCRM.modules.ALL`
  * `ZohoBooks.fullaccess.ALL`
  * `ZohoProjects.projects.ALL`
</ParamField>

### Gmail

No additional parameters required.

## Error Codes

<ResponseField name="400" type="object">
  Invalid request

  ```json theme={null}
  {
    "error": "Missing required parameters"
  }
  ```
</ResponseField>

<ResponseField name="401" type="object">
  Authentication error

  ```json theme={null}
  {
    "error": "Invalid or expired API key"
  }
  ```
</ResponseField>

<ResponseField name="500" type="object">
  Server error

  ```json theme={null}
  {
    "error": "Failed to initialize OAuth flow"
  }
  ```
</ResponseField>

## Notes

* The OAuth flow is a multi-step process:
  1. Call this endpoint to get the authorization URL
  2. Redirect the user to the authorization URL
  3. User authorizes your application
  4. Integration provider redirects to your callback URL
  5. Call the [callback endpoint](/api-reference/integrations/callback) to complete the flow
* The `passthroughRedirectUri` should be a URL in your application that can handle the OAuth callback
* Store the `externalUserIdentifier` to associate the integration with the correct user after the callback