Notion Install & Auth Skill

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:

Click New integration
Name it, select the workspace, and choose capabilities (Read content, Update content, Insert content)
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

| Error | Cause | Solution | |-------|-------|----------| | unauthorized | Invalid or expired token | Regenerate at notion.so/my-integrations | | object_not_found | Page not shared with integration | Open page > ... > Connections > add integration | | restricted_resource | Missing capabilities | Edit integration capabilities in dashboard | | validation_error | Malformed request body | Check SDK version and parameter types | | rate_limited | Too many requests (3 req/s avg) | Add exponential backoff; SDK retries automatically | | MODULE_NOT_FOUND | SDK not installed | Run 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.

Agent Skills: Notion Install & Auth

Install this agent skill to your local

Skill Files