What is the primary method for Notion API authentication?

Notion primarily uses OAuth 2.0 for public integrations that require user consent and internal integration tokens (API keys) for private, workspace-specific automations and scripts.

How do I get an API key for Notion?

You can get an internal integration token (API key) by creating a new integration in your Notion workspace settings, accessible via 'My integrations'. Notion will then provide a 'Secret API Key' for your use.

What is the difference between OAuth 2.0 and an internal integration token?

OAuth 2.0 is for public applications requiring user authorization to access their Notion data, while an internal integration token is for private, server-side applications or scripts that operate within a single Notion workspace without explicit user consent for each action.

Do Notion API tokens expire?

Internal integration tokens do not expire by default but can be revoked. OAuth access tokens typically have a limited lifespan and require refresh tokens to obtain new access tokens.

How do I grant an Notion integration access to specific pages or databases?

After creating an internal integration, you must explicitly invite it to the specific pages or databases it needs to access within the Notion UI. This is done via the 'Share' menu of the respective page or database.

What security measures should I take with Notion API keys?

Always store API keys securely using environment variables or secret management services, avoid hardcoding them, grant only necessary permissions (least privilege), and regularly rotate your keys.

Is Notion API traffic encrypted?

Yes, all communication with the Notion API is enforced over HTTPS (TLS 1.2 or higher) to ensure data encryption in transit.

Notion Authentication: API Access & Security (2026)

Authentication overview

Notion provides programmatic access to its platform through its API, allowing developers to create integrations that interact with pages, databases, and users. Secure authentication is fundamental to these interactions, ensuring that only authorized applications and users can access or modify Notion content. The platform supports different authentication mechanisms tailored for various integration types, from public applications to internal scripts. All API requests to Notion must be made over HTTPS to ensure data encryption in transit, aligning with industry standards for secure communication over the web Notion API security and best practices. Understanding the available methods and their appropriate use cases is crucial for building secure and functional Notion integrations.

The Notion API uses bearer token authentication. This means an authorization token is included in the Authorization header of HTTP requests. The specific method for obtaining this token varies depending on whether the integration is public (OAuth 2.0) or internal (integration token).

Supported authentication methods

Notion supports two primary authentication methods for its API:

OAuth 2.0 (Public Integrations): This is the recommended method for public applications that need to access Notion workspaces on behalf of various users. OAuth 2.0 allows users to grant third-party applications limited access to their Notion data without sharing their actual login credentials. Notion implements the Authorization Code Grant flow, which involves redirecting the user to Notion for authorization and then exchanging an authorization code for an access token Notion OAuth authorization guide.
Internal Integration Tokens (Internal Integrations): For private applications, scripts, or internal tools that operate within a single Notion workspace, developers can create an internal integration. This method generates a secret API key (token) that grants direct access to the workspace's data, subject to the permissions granted to the integration. These tokens are suitable for server-side applications or tools where user interaction for granting access is not required or practical.

The following table summarizes Notion's authentication methods:

Method	When to Use	Security Level
OAuth 2.0	Public applications, third-party services, multi-user access	High (user consent, token rotation)
Internal Integration Tokens	Private scripts, internal tools, single-workspace automation	Moderate (direct access, token management required)

Getting your credentials

For OAuth 2.0 (Public Integrations):

To use OAuth 2.0, you must register your application with Notion. This process involves obtaining a Client ID and Client Secret, which uniquely identify your application.

Create an integration: Navigate to My integrations in Notion and click "New integration".
Configure your integration: Provide a name, select the associated workspace, and specify the capabilities and content access for the integration.
Obtain Client ID and Client Secret: After creation, Notion will provide you with a Client ID and Client Secret. These are crucial for initiating the OAuth flow.
Set Redirect URIs: In your integration settings, specify the redirect URIs that Notion can use to send authorization codes back to your application Notion API authorization documentation.

For Internal Integration Tokens:

Internal integration tokens are simpler to set up, designed for direct, private use within a single Notion workspace.

Create an integration: Go to My integrations and click "New integration".
Configure your integration: Give it a name, select the workspace, and define its capabilities (e.g., read, update, insert content).
Copy the Internal Integration Token: Upon creation, Notion will display the "Secret API Key" (your internal integration token). Copy and store this token securely. This token grants direct access to the workspace.
Share with pages/databases: For the integration to access specific pages or databases, it must be explicitly invited to them within the Notion UI. Open the page or database, click the "Share" menu, and add your integration Notion getting started guide.

Authenticated request example

Once you have an access token (from OAuth 2.0) or an internal integration token, you include it in the Authorization header of your API requests as a Bearer token. Here's an example using curl to fetch a Notion page:

curl 'https://api.notion.com/v1/pages/<page_id>'
  -H 'Authorization: Bearer <YOUR_NOTION_TOKEN>'
  -H 'Notion-Version: 2022-06-28'
  -H 'Content-Type: application/json'

Replace <YOUR_NOTION_TOKEN> with your actual access token or internal integration token, and <page_id> with the ID of the Notion page you wish to retrieve. The Notion-Version header specifies the API version your request targets, ensuring compatibility Notion API reference.

Security best practices

Adhering to security best practices is essential when integrating with the Notion API to protect sensitive data and maintain the integrity of your workspace.

Token Security: Never hardcode API tokens or client secrets directly into your application's source code. Use environment variables, secure configuration files, or secret management services (e.g., AWS Secrets Manager, Google Cloud Secret Manager, Azure Key Vault) to store and retrieve credentials AWS Secrets Manager documentation.
Least Privilege: Grant your integrations only the minimum necessary permissions. For internal integrations, carefully select the capabilities (read, update, insert) and explicitly share them with only the required pages or databases. For OAuth applications, request only the scopes essential for your application's functionality.
HTTPS Everywhere: All communication with the Notion API must use HTTPS (TLS 1.2 or higher) to encrypt data in transit and protect against eavesdropping and tampering. The Notion API enforces this by default Notion API security practices.
Token Rotation: Regularly rotate your API tokens, especially internal integration tokens. If a token is compromised, rotating it limits the window of exposure. OAuth access tokens typically have shorter lifespans and require refresh tokens for renewal, adding a layer of security.
Error Handling and Logging: Implement robust error handling to prevent sensitive information from being exposed in error messages. Log API access and errors to monitor for unusual activity, but ensure logs do not inadvertently capture API tokens or other sensitive data.
Input Validation: Sanitize and validate all user inputs before incorporating them into API requests to prevent injection attacks and other vulnerabilities.
Rate Limiting: Be aware of Notion's API rate limits to avoid service interruptions. Design your applications to handle rate limit errors gracefully, typically by implementing exponential backoff and retry mechanisms.
Protect Redirect URIs (OAuth): For OAuth applications, ensure your redirect URIs are secured and only accessible to your application. Misconfigured redirect URIs can lead to authorization code interception attacks.
Stay Updated: Keep your application's dependencies and libraries up-to-date to patch known security vulnerabilities. Regularly review Notion's API documentation for updates to security guidelines and available features.