Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 36 ยท API and Integrations

Creating an Integration and Sharing Pages

Create a Notion internal integration, copy its token safely, choose capabilities, connect it to a page or database, and understand OAuth public integrations.

Before any script can touch your data, you need an integration: a named bot with its own token and a list of things it is allowed to do. This lesson walks through creating one, giving it access to one database, and keeping the token safe.

Notion cannot be reached from this site, so the steps are described, not demonstrated. The runnable code is a stand-in that checks the logic of capabilities and access, with example values only. The exact menu wording changes occasionally; the concepts do not.

Two kinds of integration

Kind Used for Authentication
Internal Your own workspace: scripts, automations, personal tools A secret token you copy
Public An app other workspaces install OAuth 2.0: users approve access and your app receives a token per workspace

Start with an internal integration. You only need OAuth when you are building something for other people to install.

Creating an internal integration

  1. Go to Notion's integrations dashboard (notion.so/profile/integrations, or Settings > Connections > Develop or manage integrations).
  2. Choose New integration.
  3. Give it a name, choose the workspace it belongs to, and pick the type Internal.
  4. Under Capabilities, select what it may do (see below).
  5. Save, then open the Configuration tab and show and copy the Internal Integration Secret.

Store the secret in an environment variable such as NOTION_TOKEN, never in source code you commit.

Capabilities

Capabilities are the integration's permissions, independent of what you can do yourself:

  • Read content
  • Update content
  • Insert content
  • Read comments / insert comments
  • User information: none, names only, or names plus emails

Grant the minimum. A reporting script only needs Read content. If it later needs to write, you can add capabilities. If a request returns 403, a missing capability is a likely cause.

Giving the integration access

A new integration can see nothing. You must connect it to a page or database:

  1. Open the page or database in Notion.
  2. Click the ... menu in the top right.
  3. Choose Connections (older versions: Add connections).
  4. Search for your integration and confirm.

The integration then has access to that page and everything beneath it. Connect it to the narrowest parent that covers what it needs. You can also let an integration be selected while creating it in some flows (an access picker). Removing the connection from the same menu revokes access.

Finding IDs

APIs need the ID of a database or page. In the URL of a page:

https://www.notion.so/My-Tasks-1a2b3c4d5e6f47a8b9c0d1e2f3a4b5c6?v=...

the ID is the 32 hex characters after the last hyphen of the title (before ?). The API accepts it with or without dashes.

Stand-in: extract an ID and check capabilities

The JavaScript below is a stand-in using a made-up URL and made-up capability names. It extracts the ID and decides whether an action would be permitted.

JS Stand-in: ID and capability check

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Keeping the token safe

  • Environment variable: read it with process.env.NOTION_TOKEN in Node or os.environ in Python.
  • Never commit it. Add .env to .gitignore.
  • Rotate it if it leaks: in the integration's Configuration tab, refresh the secret and update your scripts.
  • One integration per purpose. If a reporting script leaks, you can revoke it without breaking everything else.
  • Do not embed it in front-end code. Anything shipped to a browser is visible; call Notion from a server.

A note on OAuth

For a public integration, your app sends users to a Notion authorization URL, the user chooses which pages to share, Notion returns a code, and your server exchanges it for an access token tied to that workspace. The token is then used exactly like an internal one. Because it involves client secrets and redirects, build it on the server side only, and follow Notion's current OAuth documentation.

Stand-in: reading the token from the environment

This snippet shows the safe pattern: fail early if the variable is missing, and never print the secret.

JS Stand-in: safe token handling

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. A brand-new internal integration calls the API and gets 404 on your database. What is missing?

    Integrations see nothing until they are connected to a page or database.
  2. 2. Which kind of integration uses OAuth?

    Public integrations installed by other workspaces use OAuth 2.0.
  3. 3. Where is a safe place for the integration secret?

    Keep secrets out of code and out of browsers; use environment variables or a secrets manager.

Summary

  • Internal integrations use a secret token; public ones use OAuth.
  • Capabilities limit what the integration may do; grant the minimum.
  • An integration sees only pages connected to it (and their children).
  • Protect the token: environment variable, no commits, rotate on leak.

Next: Querying Databases with the API