Workspace-level tokens for public integrations will be deprecated soon; migrate your OAuth flows
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:
| Workspace-level tokens (old) | User-level tokens (new) | |
|---|---|---|
| Who can go through OAuth and grant access | Admins only | Admins and members |
| Number of access tokens per workspace | 1 | Up to N, where N is the number of admins and members |
| Who can go through OAuth and reauthorize access for a given token | Only the original user who went through OAuth to grant the token | Only the original user who went through OAuth to grant the token |
| OAuth token response | Contains an owner field with the value { workspace: true } | Contains an owner field with the value { user: <API user object> } |
| What resources an integration has access to | Pages/databases the installing user chooses via the page picker during OAuth; pages/databases the installing user and other users in the workspace share with the integration via the Page menu; children of pages/databases that were shared with the integration | Pages/databases the installing user chooses via the page picker during OAuth; pages/databases the installing user shares with the integration via the Page menu; children of pages/databases that were shared with the integration |
| What an integration can do with resources it has access to | Read and write | Read and write |
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.
- 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_idwhich 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_idreturned in the OAuth token response, since a workspace may have multiple tokens. Do not map the token to theowner.user.idin the OAuth token response, since a user may install your integration in multiple workspaces.
- To avoid overwriting tokens, do not map the token to the
- Add
&owner=userto your OAuth authorization URL (the url starting withhttps://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.