Notion OAuth Integration Setup Guide

This guide walks you through setting up a Notion OAuth integration for SurfSense.

Step 1: Access Notion Integrations

1. Navigate to notion.so/profile/integrations
2. Click the "New integration" button

Step 2: Configure New Integration

Fill in the integration details:

OAuth Redirect URI

Under OAuth domains & URIs, set the Redirect URI to:

http://localhost:8000/api/v1/auth/notion/connector/callback

Click Save to create the integration.

Step 3: Get OAuth Credentials & Configure Capabilities

After creating the integration, you'll see the configuration page with your credentials:

1. Copy your OAuth Client ID
2. Copy your OAuth Client Secret (click Refresh if needed)

Set Required Capabilities

Enable the following capabilities:

Click Save to apply the capabilities.

Limitations & Unsupported Content

Notion's API has limitations on certain block types that cannot be retrieved. SurfSense will automatically skip these unsupported blocks and continue syncing all other content.

Unsupported Block Types

The following Notion features are not accessible via the Notion API and will be skipped during sync:

• Transcription blocks - Audio/video transcriptions from Notion AI
• AI blocks - AI-generated content blocks

Learn More

The Notion API only supports specific block types for retrieval. The official list of supported block types is documented in Notion's Block reference:

• Block Object Reference - Official documentation listing all supported block types. Any block type not listed here (such as transcription and ai_block) is not accessible via the Notion API.

For additional information:

• Working with Page Content - Guide on how the Notion API handles page content
• Notion API Reference - Complete API documentation

Running SurfSense with Notion Connector

Add the Notion environment variables to your Docker run command:

docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  # Notion Connector
  -e NOTION_OAUTH_CLIENT_ID=your_notion_client_id \
  -e NOTION_OAUTH_CLIENT_SECRET=your_notion_client_secret \
  -e NOTION_REDIRECT_URI=http://localhost:8000/api/v1/auth/notion/connector/callback \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest