notion-security-basics

What this skill does

# 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](https://www.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.

```bash
# .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
```

```typescript
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:

```yaml
# .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](https://www.notion.so/my-integrations). 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:**

```typescript
// 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:**

```typescript
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

```bash
# 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.

```typescript
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_UR