Skip to main content

​
Overview

CrewAI supports integration with Notion, enabling your crews to access workspaces, databases, pages, and comments.

​
Prerequisites

  • A Notion account
  • Workspace owner or admin permissions to create integrations
  • Access to Notion Integrations

​
Notion Integration Setup

​
Step 1: Create a New Integration

  1. Navigate to Notion Integrations
  2. Click New integration
  3. Fill in the integration details:
    • Name: Enter a name (e.g., “CrewAI”)
    • Logo: Optional logo for the integration
    • Associated workspace: Select the workspace to integrate with
  4. Click Submit

​
Step 2: Configure Capabilities

  1. In your integration settings, configure the Capabilities:
    • Content Capabilities: Select what content the integration can access
    • Comment Capabilities: Enable if you need to create comments
    • User Capabilities: Enable to read user information
  2. Under OAuth Domain & URIs:
    • Redirect URIs: Add your redirect URI: Default configuration (NGINX with shared hostname): 
      https://<YOUR_APPLICATION_HOST>/oauthsvc/oauth/add
      Separate OAuth hostname (GKE/ALB with path: "/"): 
      https://<YOUR_OAUTH_HOST>/oauth/add
    When using GKE’s native ingress or a separate OAuth hostname with oauth.ingress.path: "/", the /oauthsvc prefix is not included. See OAuth Ingress Path Configuration.

​
Step 3: Get Your Credentials

  1. In the Secrets section, locate:
    • OAuth client ID: Your integration’s client ID
    • OAuth client secret: Click to reveal the secret
  2. Store these credentials securely for CrewAI configuration
Notion uses a different authentication method than typical OAuth. The integration must be explicitly shared with pages and databases in Notion before it can access them.

​
Required Scopes

Notion uses capability-based permissions rather than traditional OAuth scopes. The following scopes are used during OAuth:
ScopeDescription
read:userRead user information from the workspace
insert:commentsCreate comments on pages and discussions

​
Share Integration with Content

After OAuth authentication, users must share the integration with specific pages or databases:
  1. Open a Notion page or database
  2. Click the … menu in the top right
  3. Select Connections (or Add connections)
  4. Find and select your integration name
  5. Click Confirm
The integration can only access content that has been explicitly shared with it. This is a Notion security feature to ensure users have control over what data integrations can access.

​
Configure CrewAI Helm Values

Add your Notion credentials to your CrewAI Helm values: 
oauth:
  enabled: true
  secrets:
    notion:
      clientId: "your-notion-oauth-client-id"
      clientSecret: "your-notion-oauth-client-secret"
See Built-in Integrations Configuration for complete configuration options.

​
Activate the Integration

After deploying the updated Helm values, you must sync the integration definitions so the platform recognizes them. Use either method: Option 1: Via Admin Panel
  1. Log in to the CrewAI web UI as an admin
  2. Navigate to Admin Panel > Tools & Integrations
  3. Click the Sync Integrations button
Option 2: Via kubectl 
kubectl exec -it deploy/crewai-web -- bin/rails studio:tools:sync_crewai_tools
Until you sync, the Notion integration will not appear as available to users. Repeat this step after any Helm upgrade that changes OAuth credentials.