SOP 001: Create a Notion Integration

Fresh Last Updated: January 2025

Field	Value
SOP ID	SOP-001
Version	1.0
Status	Active
Difficulty	Beginner

Purpose

This procedure guides you through creating a Notion integration, which is required to interact with the Notion API.

Prerequisites

• [ ] Notion account with Workspace Owner permissions
• [ ] Understanding of API basics

Procedure Overview

Step-by-Step Instructions

Step 1: Access the Integrations Dashboard

1. Log in to your Notion account
2. Navigate to notion.so/profile/integrations
3. You'll see your existing integrations (if any)

Step 2: Create New Integration

1. Click + New integration button
2. Fill in the required fields:

Field	Description	Example
Name	Descriptive name for your integration	"My Task Sync"
Logo	Optional logo image	280x280px PNG
Associated workspace	Workspace to connect	"My Workspace"

3. Click Submit

Step 3: Configure Capabilities

Navigate to the Capabilities tab and configure:

Content Capabilities

Capability	When to Enable
Read content	Always (required for most operations)
Update content	Modifying existing pages/blocks
Insert content	Creating new pages/blocks
Read comments	Accessing page comments
Create comments	Adding comments to pages
Read user information	Getting user details

Principle of Least Privilege

Only enable capabilities your integration actually needs. This improves security.

Step 4: Copy Your API Secret

1. Go to the Secrets tab
2. Click Show next to the Internal Integration Secret
3. Click Copy to copy the secret

# Store in environment variable (recommended)
export NOTION_API_KEY="secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Never Expose Your Secret

• Don't commit to version control
• Don't include in client-side code
• Use environment variables or secret managers

Step 5: Grant Integration Access to Pages

Your integration cannot access any content by default. You must explicitly grant access:

1. Open the Notion page/database you want to access
2. Click ... (More menu) in the top-right corner
3. Scroll down to + Add connections
4. Search for your integration name
5. Click to add it
6. Confirm the connection

Access Inheritance

When you grant access to a page, the integration automatically has access to all child pages and databases.

Step 6: Test Your Integration

Create a test script:

require('dotenv').config();
const { Client } = require('@notionhq/client');

const notion = new Client({ auth: process.env.NOTION_API_KEY });

async function testConnection() {
  try {
    const response = await notion.users.me({});
    console.log('✅ Connected successfully!');
    console.log('Bot name:', response.name);
    console.log('Bot ID:', response.id);
    return true;
  } catch (error) {
    console.error('❌ Connection failed:', error.message);
    return false;
  }
}

testConnection();

Expected output:

✅ Connected successfully!
Bot name: My Task Sync
Bot ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Verification Checklist

• [ ] Integration created in Notion dashboard
• [ ] API secret copied and stored securely
• [ ] Required capabilities enabled
• [ ] At least one page has integration access
• [ ] Test script connects successfully

Troubleshooting

Issue	Cause	Solution
401 Unauthorized	Invalid or missing API key	Verify API key is correct
403 Forbidden	Missing capabilities	Enable required capabilities
404 Not Found	Page not shared with integration	Add integration to page
Rate limited	Too many requests	Implement backoff strategy

Common Mistakes

1. Forgetting to grant page access - The most common issue. Always add your integration to the specific pages it needs.

2. Using the wrong secret - Make sure you're using the "Internal Integration Secret", not OAuth credentials.

3. Insufficient capabilities - If operations fail, check if you have the required capability enabled.

See Also

• SOP 002: Authentication Setup
• Quick Reference: Error Codes
• Official: Authorization Guide