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 :

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 objectnotfound.

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

Examples

Minimal Node.js client — pin the API version and verify before doing real work:

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

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

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

For the complete TypeScript and Python setups — client timeouts, users.list()

access checks, per-line notes, and a "what success looks like" checklist — see

full setup examples.

Resources

• Notion API Authorization
• Create an Integration
• @notionhq/client on npm
• notion-client on PyPI
• API Reference

Next Steps

After successful auth, proceed to the notion-hello-world skill for your first

page query. From there, share additional databases with the integration through

the Connections menu and grant only the capabilities each workflow needs —

Notion enforces both the token scope and the per-page share, so widen access

deliberately rather than up front.