Skills Development Setting Up Notion API Authentication

Setting Up Notion API Authentication

v20260423
notion-install-auth
This guide provides a comprehensive walkthrough for installing and configuring the Notion API SDK in both Node.js and Python environments. It covers creating internal integrations, securely setting environment variables for the API token, and verifying connectivity. Necessary for any developer building applications that interact with Notion workspaces and databases.
Get Skill
324 downloads
Overview

Notion Install & Auth

Overview

Set up the official Notion SDK and configure authentication for internal integrations. The Node.js SDK is @notionhq/client (npm) and the Python SDK is notion-client (pip). Both wrap the Notion API at https://api.notion.com/v1 using API version 2022-06-28.

Prerequisites

  • Node.js 18+ or Python 3.8+
  • Package manager (npm, pnpm, yarn, or pip)
  • A Notion account (free or paid)
  • Access to My Integrations dashboard

Instructions

Step 1: Create Integration and Install SDK

Create an internal integration at https://www.notion.so/my-integrations:

  1. Click New integration
  2. Name it, select the workspace, and choose capabilities (Read content, Update content, Insert content)
  3. Copy the Internal Integration Secret (starts with ntn_ or secret_)

Install the SDK:

# Node.js / TypeScript (official SDK)
npm install @notionhq/client

# Python (official SDK)
pip install notion-client

Step 2: Configure Authentication

Store the token in environment variables -- never hardcode it:

# Set environment variable
export NOTION_TOKEN="ntn_your_integration_secret_here"

# Or add to .env file (add .env to .gitignore)
echo 'NOTION_TOKEN=ntn_your_integration_secret_here' >> .env

Share pages with your integration: In Notion, open the page or database you want to access. Click the ... menu, select Connections, and add your integration. Without this step, all API calls return object_not_found.

Step 3: Verify Connection

import { Client } from '@notionhq/client';

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

const me = await notion.users.me({});
console.log(`Authenticated as: ${me.name} (${me.type})`);
console.log(`Bot ID: ${me.id}`);

If the bot user is returned, authentication is working.

Output

  • SDK package installed (@notionhq/client for Node.js, notion-client for Python)
  • Environment variable NOTION_TOKEN configured
  • Integration connected to target pages/databases via Connections menu
  • Verified API connectivity with users.me() call

Error Handling

ErrorCauseSolution
unauthorizedInvalid or expired tokenRegenerate at notion.so/my-integrations
object_not_foundPage not shared with integrationOpen page > ... > Connections > add integration
restricted_resourceMissing capabilitiesEdit integration capabilities in dashboard
validation_errorMalformed request bodyCheck SDK version and parameter types
rate_limitedToo many requests (3 req/s avg)Add exponential backoff; SDK retries automatically
MODULE_NOT_FOUNDSDK not installedRun npm install @notionhq/client

Examples

TypeScript — Full Setup

import { Client } from '@notionhq/client';

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  timeoutMs: 60_000,
  notionVersion: '2022-06-28',
});

// Verify connection
const me = await notion.users.me({});
console.log(`Connected as ${me.name}`);

// List all users in the workspace
const users = await notion.users.list({});
console.log(`Workspace has ${users.results.length} users`);

Python — Full Setup

import os
from notion_client import Client

notion = Client(auth=os.environ["NOTION_TOKEN"])

# Verify connection
me = notion.users.me()
print(f"Connected as {me['name']} ({me['type']})")

# List all users in the workspace
users = notion.users.list()
print(f"Workspace has {len(users['results'])} users")

Resources

Next Steps

After successful auth, proceed to notion-hello-world for your first page query.

Info
Category Development
Name notion-install-auth
Version v20260423
Size 4.61KB
Updated At 2026-04-28
Language