Agent Skills: Notion Security Basics

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.

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.

# .gitignore — add these patterns BEFORE creating .env
.env
.env.local
.env.*.local
.env.production
.env.staging

# .env.example — commit this template (no real values)
NOTION_TOKEN=ntn_your_internal_integration_token_here
NOTION_OAUTH_CLIENT_ID=
NOTION_OAUTH_CLIENT_SECRET=
NOTION_OAUTH_REDIRECT_URI=http://localhost:3000/auth/notion/callback

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

// Always load tokens from environment — never hardcode
const token = process.env.NOTION_TOKEN;

if (!token) {
  throw new Error(
    'NOTION_TOKEN is required. ' +
    'Create an integration at https://www.notion.so/my-integrations ' +
    'and set the token in your .env file.'
  );
}

// Validate token format before using it
if (!token.startsWith('ntn_') && !token.startsWith('secret_')) {
  throw new Error(
    'NOTION_TOKEN has an unexpected format. ' +
    'Internal integration tokens start with ntn_ (or legacy secret_).'
  );
}

const notion = new Client({ auth: token });

Git secret scanning to catch accidental commits:

# .github/workflows/secret-scan.yml
name: Secret Scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check for Notion tokens
        run: |
          # Scan for internal integration tokens
          if grep -rE "(ntn_|secret_)[a-zA-Z0-9]{30,}" \
            --include="*.ts" --include="*.js" --include="*.json" \
            --include="*.yaml" --include="*.yml" --include="*.env" .; then
            echo "::error::Notion token found in source code! Rotate immediately."
            exit 1
          fi

Step 2: Least-Privilege Capabilities and Access Auditing

Configure integration capabilities at the integration dashboard. Each integration should request only the capabilities it actually uses.

| Capability | Grant when... | Do NOT grant for... | |------------|---------------|---------------------| | Read content | Reading pages, databases, blocks | Write-only bots (form submissions) | | Update content | Modifying existing page properties/blocks | Read-only dashboards | | Insert content | Creating new pages, appending blocks | Analytics/reporting tools | | Read comments | Listing and reading page comments | Data sync pipelines | | Create comments | Adding comments to discussions | Read-only integrations | | Read user info (with email) | User lookup by email address | Most integrations | | Read user info (without email) | Resolving user references in properties | None (safe default) |

Separate integrations by responsibility:

// Create distinct integrations with different capabilities:
// "acme-reader" — Read content only
// "acme-writer" — Read + Update + Insert content

const readerNotion = new Client({ auth: process.env.NOTION_READ_TOKEN });
const writerNotion = new Client({ auth: process.env.NOTION_WRITE_TOKEN });

// Dashboards and reporting use the reader
const results = await readerNotion.databases.query({
  database_id: process.env.NOTION_DATABASE_ID!,
  filter: {
    property: 'Status',
    select: { equals: 'Published' },
  },
});

// Mutations use the writer only when needed
await writerNotion.pages.update({
  page_id: pageId,
  properties: {
    'Last Synced': {
      date: { start: new Date().toISOString() },
    },
  },
});

Audit which pages are shared with an integration:

async function auditIntegrationAccess(notion: Client): Promise<void> {
  // Search with empty query returns all pages the integration can access
  let hasMore = true;
  let startCursor: string | undefined;
  const accessiblePages: Array<{ id: string; title: string; type: string }> = [];

  while (hasMore) {
    const response = await notion.search({
      start_cursor: startCursor,
      page_size: 100,
    });

    for (const result of response.results) {
      if (result.object === 'page') {
        const titleProp = Object.values((result as any).properties || {})
          .find((p: any) => p.type === 'title') as any;
        const title = titleProp?.title?.[0]?.plain_text || '(untitled)';
        accessiblePages.push({ id: result.id, title, type: 'page' });
      } else if (result.object === 'database') {
        const title = (result as any).title?.[0]?.plain_text || '(untitled)';
        accessiblePages.push({ id: result.id, title, type: 'database' });
      }
    }

    hasMore = response.has_more;
    startCursor = response.next_cursor ?? undefined;
  }

  console.log(`Integration has access to ${accessiblePages.length} objects:`);
  for (const page of accessiblePages) {
    console.log(`  [${page.type}] ${page.title} (${page.id})`);
  }
}

Page sharing hierarchy rules:

• Sharing a parent page grants access to all child pages and databases
• Sharing a child page alone does NOT grant access to its parent
• Removing integration access from a parent cascades to all children
• The API returns object_not_found for both non-existent pages and unshared pages — this is intentional to prevent information leakage

Step 3: Token Rotation, OAuth2, and Webhook Verification

Token Rotation for Internal Integrations

# 1. Go to notion.so/my-integrations → select integration
#    Click "Show" under Internal Integration Secret → "Regenerate"
#    WARNING: regeneration immediately invalidates the old token

# 2. Update the secret in your deployment platform FIRST
# AWS Secrets Manager:
aws secretsmanager update-secret \
  --secret-id notion/integration-token \
  --secret-string "ntn_new_token_value"

# GCP Secret Manager:
echo -n "ntn_new_token_value" | \
  gcloud secrets versions add notion-integration-token --data-file=-

# Vault:
vault kv put secret/notion token="ntn_new_token_value"

# 3. Restart services to pick up the new secret

# 4. Verify the new token works
curl -s https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer ${NOTION_TOKEN}" \
  -H "Notion-Version: 2022-06-28" | jq '.name // .bot'

# 5. Old token is already invalidated (step 1), no separate revocation needed

OAuth2 Flow for Public Integrations

Public integrations use OAuth2 to let users authorize access without sharing raw tokens. This is required when distributing your integration to other Notion workspaces.

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

const app = express();
const OAUTH_CLIENT_ID = process.env.NOTION_OAUTH_CLIENT_ID!;
const OAUTH_CLIENT_SECRET = process.env.NOTION_OAUTH_CLIENT_SECRET!;
const REDIRECT_URI = process.env.NOTION_OAUTH_REDIRECT_URI!;

// Step A: Redirect user to Notion's authorization page
app.get('/auth/notion', (req, res) => {
  const authUrl = new URL('https://api.notion.com/v1/oauth/authorize');
  authUrl.searchParams.set('client_id', OAUTH_CLIENT_ID);
  authUrl.searchParams.set('response_type', 'code');
  authUrl.searchParams.set('redirect_uri', REDIRECT_URI);
  authUrl.searchParams.set('owner', 'user'); // or 'workspace'

  // Generate and store a state parameter to prevent CSRF
  const state = crypto.randomUUID();
  req.session.oauthState = state;
  authUrl.searchParams.set('state', state);

  res.redirect(authUrl.toString());
});

// Step B: Exchange authorization code for access token
app.get('/auth/notion/callback', async (req, res) => {
  const { code, state } = req.query;

  // Verify state parameter matches what we sent
  if (state !== req.session.oauthState) {
    return res.status(403).send('Invalid state parameter — possible CSRF attack');
  }

  // Exchange code for token using Basic auth (client_id:client_secret)
  const credentials = Buffer.from(
    `${OAUTH_CLIENT_ID}:${OAUTH_CLIENT_SECRET}`
  ).toString('base64');

  const tokenResponse = await fetch('https://api.notion.com/v1/oauth/token', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${credentials}`,
      'Content-Type': 'application/json',
      'Notion-Version': '2022-06-28',
    },
    body: JSON.stringify({
      grant_type: 'authorization_code',
      code,
      redirect_uri: REDIRECT_URI,
    }),
  });

  const tokenData = await tokenResponse.json();

  if (!tokenResponse.ok) {
    console.error('OAuth token exchange failed:', tokenData);
    return res.status(400).send('Authorization failed');
  }

  // tokenData contains:
  // - access_token: the integration token for this workspace
  // - workspace_id: the workspace that authorized the integration
  // - workspace_name, workspace_icon, bot_id, owner
  // Store access_token securely (encrypted in database, not in cookies)
  await storeToken(tokenData.workspace_id, tokenData.access_token);

  // Use the token with the Notion client
  const notion = new Client({ auth: tokenData.access_token });
  const me = await notion.users.me({});
  console.log(`Authorized for workspace: ${tokenData.workspace_name}`);

  res.redirect('/dashboard');
});

Webhook Verification

// Notion webhooks require URL verification during setup
// and should be validated on every incoming request

app.post('/webhooks/notion', express.json(), async (req, res) => {
  // Notion verifies your endpoint during registration
  if (req.body.type === 'url_verification') {
    return res.json({ challenge: req.body.challenge });
  }

  // Validate the payload structure
  if (!req.body.type || !req.body.data) {
    return res.status(400).json({ error: 'Invalid webhook payload' });
  }

  // Always respond 200 quickly — process the event asynchronously
  res.status(200).json({ ok: true });

  // Process event outside the request cycle
  try {
    await processWebhookEvent(req.body);
  } catch (error) {
    console.error('Webhook processing failed:', error);
  }
});

// Additional hardening:
// 1. Only accept HTTPS connections (terminate TLS at load balancer)
// 2. Validate Content-Type is application/json
// 3. Rate limit the webhook endpoint (e.g., 100 req/min)
// 4. Log all incoming events for audit trail

Output

After applying this skill:

• Integration tokens stored in environment variables, never in source code
• .gitignore configured to exclude all .env variants
• Git secret scanning workflow catches accidental token commits
• Integration capabilities set to the minimum required for each role
• Page access audited — you know exactly which pages the integration can reach
• Token rotation procedure documented with cloud provider commands
• OAuth2 flow implemented for public integrations (if applicable)
• Webhook endpoint validates payloads and responds asynchronously

Error Handling

| Security Issue | Detection | Mitigation | |----------------|-----------|------------| | Token committed to git | CI secret scan, git log -p -S 'ntn_' | Rotate immediately, rewrite git history with git filter-repo | | Over-privileged integration | Capability audit at dashboard | Create new integration with minimal capabilities, migrate | | Stale access to removed pages | Access audit script returns unexpected pages | Revoke page sharing, re-audit | | Token never rotated | Track created_time of integration | Schedule quarterly rotation, automate with secrets manager | | OAuth state mismatch | CSRF validation in callback | Reject the request, log the attempt | | Webhook replay attacks | Duplicate event IDs | Track processed event IDs, skip duplicates |

Examples

Full .env Setup for Dual Integration Architecture

# .env — never committed
# Reader integration (Read content only)
NOTION_READ_TOKEN=ntn_reader_integration_token

# Writer integration (Read + Update + Insert)
NOTION_WRITE_TOKEN=ntn_writer_integration_token

# OAuth2 (public integration only)
NOTION_OAUTH_CLIENT_ID=abc123
NOTION_OAUTH_CLIENT_SECRET=secret_abc123
NOTION_OAUTH_REDIRECT_URI=https://app.example.com/auth/notion/callback

# Target resources
NOTION_DATABASE_ID=your_database_id

Startup Validation Script

// validate-notion-config.ts — run at application startup
import { Client } from '@notionhq/client';

async function validateNotionConfig(): Promise<void> {
  const requiredVars = ['NOTION_READ_TOKEN', 'NOTION_DATABASE_ID'];
  const missing = requiredVars.filter((v) => !process.env[v]);

  if (missing.length > 0) {
    throw new Error(`Missing required env vars: ${missing.join(', ')}`);
  }

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

  // Verify token is valid
  try {
    const me = await notion.users.me({});
    console.log(`Notion auth OK: bot "${me.name}" (${me.id})`);
  } catch (error: any) {
    if (error.code === 'unauthorized') {
      throw new Error('NOTION_READ_TOKEN is invalid or expired — rotate at notion.so/my-integrations');
    }
    throw error;
  }

  // Verify database is accessible
  try {
    await notion.databases.retrieve({
      database_id: process.env.NOTION_DATABASE_ID!,
    });
    console.log('Notion database access OK');
  } catch (error: any) {
    if (error.code === 'object_not_found') {
      throw new Error(
        'NOTION_DATABASE_ID not found — ensure the database is shared with the integration'
      );
    }
    throw error;
  }
}

validateNotionConfig().catch((err) => {
  console.error('Notion configuration validation failed:', err.message);
  process.exit(1);
});

Resources

• Notion API Authorization — token types, OAuth2 flow, scopes
• Create a Notion Integration — capabilities configuration
• API Key Best Practices — storage and rotation
• @notionhq/client npm — official SDK documentation
• Notion API Reference — full endpoint reference

Next Steps

For production deployment checklists, see notion-prod-checklist. For rate limit handling and retry strategies, see notion-rate-limits. For enterprise RBAC patterns with Notion, see notion-enterprise-rbac.