Historical changelog

Starting today we will be changing who can authorize public integrations in Notion workspaces. The previously released authorization method will be fully deprecated on October 19.

About the change

Currently OAuth tokens function on a workspace level: only admins in a workspace can grant access and there can only be one token per workspace per integration. After a brief transition period (see “How to prepare for this change” below) we will be switching exclusively to user-level tokens. These can be granted by any admin or member in the workspace, and there can be as many tokens per workspace as there are admins and members in the workspace.

See the table for the differences between these two methods:

Parameters: See API reference documentation for detailed parameters.

How to prepare for this change:

This change only affects public integrations; that is, integrations that can be installed across many workspaces via OAuth. It does not affect internal integrations.

1. Ensure that you can store and handle multiple Notion API tokens per workspace where your integration is granted access. You may map tokens directly to the bot_id which is returned in the OAuth token response and is guaranteed to be unique per API token.
   • To avoid overwriting tokens, do not map the token to the workspace_id returned in the OAuth token response, since a workspace may have multiple tokens. Do not map the token to the owner.user.id in the OAuth token response, since a user may install your integration in multiple workspaces.
2. Add &owner=user to your OAuth authorization URL (the url starting with https://api.notion.com/v1/oauth/authorize) once your application is ready for user-level tokens.

What to expect on October 19

On October 19, we will migrate all existing workspace-level tokens to user-level tokens. We will also default to creating user-level tokens when a user goes through OAuth, regardless of the owner parameter in the OAuth URL.