Authentication

To interact with the Notion API, your application needs to authenticate its requests. This guide covers the primary method for authentication using integration tokens.

Integration Tokens

The most common way to authenticate with the Notion API is by using an integration token. An integration can be either an internal integration, which is private to your workspace, or a public integration, which can be used by other Notion users.

Creating an Integration

To get your integration token, you'll need to create an integration on the Notion website.

1. Go to My Integrations

2. Click "+ New integration"

3. Give it a name, select the associated workspace, and configure its capabilities

4. Click "Save" to create the integration

Once created, you'll find your "Internal Integration Token" under the "Secrets" section. This is the token you'll use to authenticate.

For a detailed walkthrough, follow Notion's official guide to creating an integration.

Using the Token

To use your token, pass it to the using the class.

<?php
require_once 'vendor/autoload.php';

use Brd6\NotionSdkPhp\Client;
use Brd6\NotionSdkPhp\ClientOptions;

// Initialize the client options
$options = (new ClientOptions())->setAuth('YOUR_NOTION_TOKEN');

// Initialize the client
$notion = new Client($options);

// You are now ready to make requests!

Security Best Practice

Avoid hardcoding your token directly in the source code. Instead, use an environment variable (e.g., ) and load it in your application. Libraries like can help you manage environment variables easily.

// Example using getenv()
$token = getenv('NOTION_TOKEN');
$options = (new ClientOptions())->setAuth($token);

OAuth 2.0 for Public Integrations

If you are building a public application that needs to access other users' Notion workspaces, you should use the OAuth 2.0 flow. This is a more complex but secure process that allows users to grant your application specific permissions without sharing their integration tokens.

The OAuth flow involves redirecting users to Notion to authorize your app and then handling a callback to exchange a code for an access token.

For a complete, practical example of how to implement the OAuth 2.0 flow, please see our detailed guide: Example: OAuth Flow.

Next Steps

With authentication configured, you're ready to start making requests. Let's create your first page in the Your first request guide.