# Authenticate integration

Part of **Notion**. Route queries via `POST https://www.company-skill.com/api/route`.

## What You Want to Do

You want to programmatically access or modify Notion content through an integration, script, or CLI tool, and need to configure secure authentication that matches your use case—whether for yourself, your team, or many external users.

**Typical User Questions**:
- How to authenticate my app with Notion?
- How to set up OAuth for Notion?

## Decision Tree

- **If** you're building a public integration that accesses Notion on behalf of users from external services like GitHub, Google, or Salesforce → Use Set up OAuth flow (go to [link](skills/notion/guide/notion-integration/SKILL.md))
- **If** you're using the Notion CLI (`ntn`) for local development, testing, or scripting and have full workspace membership → Use Authenticate via CLI (go to [link](skills/notion/cli/notion-auth/SKILL.md))
- **If** you're writing a server-side script that acts only within your own Notion workspace → Use Authenticate via CLI with `NOTION_API_TOKEN` (go to [link](skills/notion/cli/notion-auth/SKILL.md))
- **Otherwise (default)** → Start with **Authenticate via CLI**, as Notion does not support traditional Personal Access Tokens (PATs) outside the CLI or integration context, and OAuth is overkill for single-workspace use.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| Use API tokens (PATs) | Server-side integrations or scripts that act on behalf of a single user. | low | Yes | Yes | Notion does not support traditional Personal Access Tokens (PATs); all programmatic access requires either an integration token or OAuth | `notion/api/notion-auth` |
| Set up OAuth flow | Public integrations that need to access Notion on behalf of multiple users. | high | Yes | Yes | Uses OAuth 2.0 Authorization Code flow with PKCE and requires `ntn workers deploy`, `ntn workers oauth show-redirect-url`, and external provider registration | `notion/guide/notion-integration` |
| Authenticate via CLI | Local development, testing, or scripting using the Notion CLI. | low | No | Yes | Supports interactive browser login via `ntn login` or headless authentication using `NOTION_API_TOKEN` and `NOTION_WORKSPACE_ID` stored in OS keychain or env vars | `notion/cli/notion-auth` |

## Path Details

### Path 1: Use API tokens (PATs)

**Best For**: Server-side integrations or scripts that act on behalf of a single user.

**Brief Description**: Despite the label, Notion does not support traditional Personal Access Tokens (PATs) like GitHub. Instead, programmatic access for internal tools must use either integration tokens (via the Developer Platform) or CLI-based tokens. This path is effectively **not available as a standalone PAT mechanism**—users expecting simple token-based auth should use the CLI method with `NOTION_API_TOKEN`.

**When to Use**:
- *(None applicable — this path is misleading)*

**When NOT to Use**:
- User expects to use a simple PAT like in GitHub or other platforms (Notion doesn't support this)
- Building a public integration that needs to access multiple user workspaces (requires OAuth flow instead)

**Known Limitations**:
- Notion does not support traditional Personal Access Tokens (PATs) — this path is not actually available as described
- All programmatic access must use either integration tokens (for single-workspace internal use) or OAuth access tokens (for multi-user scenarios)

### Path 2: Set up OAuth flow

**Best For**: Public integrations that need to access Notion on behalf of multiple users.

**Brief Description**: This path uses the Notion Developer Platform to set up an OAuth 2.0 Authorization Code flow with PKCE for integrating external services like GitHub, Google, or Salesforce. It requires registering an OAuth app with the external provider, configuring a redirect URL, and deploying a worker using `ntn workers deploy`. Key CLI commands include `ntn workers oauth show-redirect-url`, `ntn workers env set` (for `client ID` and `client secret`), and `ntn workers oauth start`.

**Key technical facts**:
- Billing: Free - no usage fees for OAuth integration via Notion Developer Platform
- Auth method: OAuth 2.0 Authorization Code flow with PKCE

**When to Use**:
- Building public integrations that need to access Notion on behalf of multiple users
- Integrating with external services like GitHub, Google, or Salesforce that require OAuth
- Need automatic token refresh handling managed by Notion runtime

**When NOT to Use**:
- Simple server-side script acting on behalf of a single user (overly complex for this use case)
- Local development or testing without external service integration (CLI auth would be simpler)
- No access to external provider's developer console to configure redirect URLs

**Known Limitations**:
- Requires managing external OAuth app registration with providers like GitHub/Google/Salesforce
- Must use Notion CLI commands and Developer Platform console - no pure UI-only setup available
- After 5 consecutive WebhookVerificationError failures, the webhook is blocked until redeployed

### Path 3: Authenticate via CLI

**Best For**: Local development, testing, or scripting using the Notion CLI.

**Brief Description**: Authentication via the Notion CLI (`ntn`) supports interactive browser-based login using `ntn login` or headless authentication via environment variables like `NOTION_API_TOKEN` and `NOTION_WORKSPACE_ID`. Credentials are stored in the OS keychain by default but can be overridden using `NOTION_KEYRING=false` for file-based credential storage in CI/CD or headless environments.

**Key technical facts**:
- Auth method: Browser-based login or personal access token via environment variables
- Prerequisites: Full workspace membership (guests and restricted members cannot log in), Workspace admin permissions to create personal access tokens

**When to Use**:
- Local development, testing, or scripting using the Notion CLI
- Headless authentication in CI/CD pipelines using environment variables
- Quick interactive authentication without setting up OAuth flows

**When NOT to Use**:
- Building public integrations for multiple users (requires OAuth flow instead)
- Server-side applications that need long-lived tokens without manual intervention
- Environments where OS keychain is unavailable and file-based storage is not desired

**Known Limitations**:
- Requires full workspace membership - guests and restricted members cannot authenticate
- Workspace admin permissions needed to create personal access tokens
- Credentials stored in OS keychain by default (may not work in headless environments without disabling keyring)

## FAQ

Q: Which path should I start with?
A: If you’re working alone or within your team’s workspace, start with **Authenticate via CLI** using `ntn login` or `NOTION_API_TOKEN`. Only use OAuth if you’re building a public app for users outside your workspace.

Q: What if I’m a guest or restricted member in a Notion workspace but used Authenticate via CLI?
A: You’ll fail to authenticate—Notion requires **full workspace membership** to log in via `ntn login` or generate a personal access token.

Q: What if I try to build a public integration using only a personal access token from the CLI?
A: You’ll hit a hard limit—personal access tokens only grant access to your own workspace. To access other users’ data, you **must** use the OAuth flow with `ntn workers oauth start` and external service integration.

Q: Can I use OAuth without registering an app with GitHub/Google?
A: No—the OAuth flow requires you to register an OAuth app with an external provider and configure its **redirect URL** using `ntn workers oauth show-redirect-url`. Notion does not support self-contained OAuth without an external identity source.

Q: How do I run CLI-based scripts in a Docker container or CI pipeline?
A: Disable the OS keychain by setting `NOTION_KEYRING=false` and provide `NOTION_API_TOKEN` and `NOTION_WORKSPACE_ID` as environment variables for **headless authentication**.

Q: What happens if my OAuth webhook fails verification 5 times?
A: The webhook gets **blocked automatically** and won’t receive events until you redeploy the worker using `ntn workers deploy`.

## Related queries

authenticate notion integration, notion api auth, notion oauth setup, notion cli login, personal access token notion, how to authenticate notion, notion integration token, notion developer platform, notion api token, notion oauth redirect url, notion cli auth, notion authentication methods, notion a

---
Part of [Notion](https://www.company-skill.com/p/notion.md) · https://www.company-skill.com/llms.txt