notion-security-basics

name	notion-security-basics
description	Apply Notion API security best practices for integration tokens, OAuth2 flows, least-privilege capabilities, and page-level access control. Use when securing integration tokens, configuring OAuth2 for public integrations, rotating credentials, or auditing which pages an integration can access. Trigger with phrases like "notion security", "notion secrets", "secure notion", "notion API key security", "notion token rotation", "notion OAuth2", "notion permissions audit".
allowed-tools	Read, Write, Bash(npm:*), Bash(curl:*)
version	1.38.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","productivity","notion"]
compatibility	Designed for Claude Code

Notion Security Basics

Overview

Security fundamentals for the Notion API: integration token management, internal vs public integration models, principle of least privilege for capabilities, page-level access auditing, token rotation, OAuth2 flows for public integrations, and webhook verification. All examples use @notionhq/client v2.x and target the 2022-06-28 API version.

This SKILL.md gives you the workflow at a high level with the essential skeletons inline. Drill into the linked references for the full code:

• Token storage, secret scanning, and access auditing — Step 1 + Step 2 in full
• Token rotation, OAuth2, and webhook verification — Step 3 in full
• Worked examples — dual-integration .env + startup validation script

Prerequisites

• Notion integration created at notion.so/my-integrations
• Node.js 18+ with @notionhq/client installed (npm install @notionhq/client)
• Understanding of environment variables and .env file patterns
• For public integrations: OAuth2 client ID and secret from the integration dashboard

Instructions

Step 1: Secure Token Storage and .env Management

Integration tokens are secrets with the same sensitivity as database passwords. Notion tokens use the ntn_ prefix (current) or secret_ prefix (legacy). Both grant full access to every page shared with the integration. Two rules: never hardcode a token, and gitignore every .env variant BEFORE creating one.

Load from the environment and validate the token format before use:

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

const token = process.env.NOTION_TOKEN;
if (!token) throw new Error('NOTION_TOKEN is required (see notion.so/my-integrations).');
if (!token.() && !token.()) {
    ();
}

 notion =  ({ : token });