What we need

[] API Token

This guide explains how to create and use a Notion API token for integrating with Notion workspaces.

Overview

Notion provides an API that allows developers to programmatically interact with Notion workspaces. To use the Notion API, you need to create an integration and obtain an API token. Notion offers two types of integrations:

1. Internal Integrations: Limited to a specific workspace and simpler to set up
2. Public Integrations: Can be used across multiple workspaces and require an OAuth flow

Creating a Notion Integration

Prerequisites

• A Notion account
• Workspace Owner or Admin permissions in the workspace you want to integrate with

Steps to Create an Internal Integration

1. Go to your Notion account settings by clicking on your profile picture in the bottom-left corner and selecting “Settings & members”
2. Navigate to the “Integrations” tab
3. Click on “Develop or manage integrations” at the bottom of the page (or go directly to https://www.notion.so/my-integrations)
4. Click the “+ New integration” button
5. Fill in the following details:
   • Name: Give your integration a descriptive name
   • Logo (optional): Upload an image for your integration
   • Associated workspace: Select the workspace where you want to use this integration
   • Make sure the integration is Private
6. Click “Submit” to create the integration

On the new integration page, make sure you enable the following capabilities:

• Read Content
• Read comments
• Read user information including email addresses

Obtaining the API Token

1. After creating the integration, you’ll be taken to the integration’s settings page
2. On the Configuration tab, you’ll see an “Internal Integration Secret” that you can copy

This secret token is what you need to provide for API authentication.

Granting Team Spaces and Pages Access to Your Integration

Before your integration can access content in your Notion workspace, you need to explicitly share pages with it:

1. On the integration you created, go to the “Access” tab
2. Add the team spaces or pages you want the integration to be able to access
3. We recommend giving access to the top-level team space for comprehensive coverage

This step is crucial - your integration can only access pages that have been explicitly shared with it.

Testing the API Token

You can verify that your token is working correctly by running the following example request:

curl 'https://api.notion.com/v1/users' \
  -H 'Authorization: Bearer YOUR_NOTION_API_TOKEN_HERE' \
  -H 'Notion-Version: 2022-06-28'

Replace YOUR_NOTION_API_TOKEN_HERE with your actual integration secret.

Support

For questions about the Notion API, visit the Notion Developer Forum.