> ## Content Index
> Fetch the complete content index at: https://notionsolutions.net/llms.txt
> Use this file to discover other available public pages before exploring further.

# Notion API Key: How to Get, Store and Check Your Token
- URL: https://notionsolutions.net/notion-api-key/
- Published: 2026-11-06T15:00:00.000Z
- Updated: 2026-11-21T04:08:47.000Z
- Description: For your own script or a paste-a-token tool, create a personal access token in the Developer portal; for a team automation, a workspace owner creates an internal connection. Store the key in an environment variable, check it with GET /v1/users/me, and know how to rotate or revoke it.
- Author: Kevin Turner
- Tags: guide, automations

**To get a Notion API key for your own script, or a tool that asks you to paste one, create a personal access token: open Personal access tokens in the Developer portal, select New token, pick the Notion API capability and select Create token. For a team automation, a workspace owner creates an internal connection and shares the pages it needs. An app other people install uses a public connection, which each user authorizes through OAuth. Copy it once, store it in an environment variable and check it with `GET /v1/users/me`.**

I'd start with a personal access token (PAT) on a short expiration, because it works with the pages you can already open and you can revoke it from the Developer portal the moment the experiment ends. For a personal script, a notebook or a no-code tool that should act as you, choose a PAT. For a sync, a notification flow or a dashboard that has to keep working after you leave the workspace, choose an internal connection, because its access belongs to the connection rather than to a person. Older tutorials call both of these "integrations" and the value an "Internal Integration Secret"; the old-name map further down translates them.

## Which Notion API key do you need?

Notion's [overview of connections and tokens](https://developers.notion.com/guides/get-started/overview?ref=notionsolutions.net) describes four access options: personal access tokens, internal connections, OAuth integrations for selected workspaces, and public integrations for any workspace. The table groups the two OAuth options because they share an authorization flow. The right one depends on who should own the access, and the table puts the deciding facts side by side.

__Personal access token, internal connection or public connection__
| Credential                             | Use it for                                                                                                                                   | Who can create it                                                                     | What it can reach                                                        | Whose access it uses                                                                                          | Where the value comes from                                               |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Personal access token                  | Your own scripts, notebooks and command-line tools, and third-party tools that ask you to paste a token and should act with your permissions | Full workspace members the workspace's PAT policy allows; workspace owners always can | Everything its creator can access, with no page sharing needed           | The creator's. If the creator leaves the workspace or loses access to a page, the token loses that access too | Shown once, right after you select Create token                          |
| Internal connection                    | Team-owned automations in one workspace, such as syncs, notifications and internal dashboards                                                | A workspace owner                                                                     | Only the pages and databases shared with it, including their child pages | Its own bot user. Pages shared with it stay shared even if the member who shared them leaves                  | The API token on the connection's Configuration tab                      |
| OAuth integration / public integration | An app whose users authorize their own access: selected workspaces for an OAuth integration, or any workspace for a public integration       | The app's developer, in the Developer portal; then each user authorizes it            | The pages each user selects in the OAuth page picker                     | The user who authorized it; every workspace member authorizes separately                                      | Your server exchanges a temporary authorization code for an access token |

One question settles most cases. If the work should stop when your own access stops, a personal access token fits. If the work belongs to the team, it needs a credential that isn't tied to your account.

[![Notion Personal access tokens list with the blue New token button](https://storage.ghost.io/c/5c/30/5c30c46b-86a3-4d20-984f-4f6ae8ad1ed2/content/images/2026/11/notion-api-key-native-new-token-20261121.webp)](https://storage.ghost.io/c/5c/30/5c30c46b-86a3-4d20-984f-4f6ae8ad1ed2/content/images/2026/11/notion-api-key-native-new-token-20261121.webp?ref=notionsolutions.net)

Choose New token to start creating a personal access token.

## How to create a personal access token

Notion's [personal access token guide](https://developers.notion.com/guides/get-started/personal-access-tokens?ref=notionsolutions.net) gives four steps, all in the Developer portal:

1. Open **Personal access tokens** in the Developer portal.
2. Select **New token**.
3. Name the token, then choose its capabilities and expiration. If a workspace picker appears, select the workspace the token belongs to.
4. Select **Create token**, then copy the value and store it somewhere secure. Notion doesn't show it again.

A token can carry two capabilities. **Notion API** lets it read, create, update and search content, read and create comments, and read supported user information through the REST API. **Workers** covers deploying and managing Notion Workers with the Notion CLI. For a script or a paste-a-token tool, Notion API is the one you need.

The **Expiration** choices are 7 days, 30 days, 90 days, 180 days or 1 year, and the form shows the exact expiration date before and after you create the token. If you don't choose, the token expires after 1 year, and an expired token returns an `unauthorized` error. I'd pick 7 or 30 days for an experiment and keep the longer options for a script you've decided to run for months, so a forgotten token doesn't stay valid for a year.

Name each token after the script or tool that uses it. The guide recommends a separate token per script, tool or environment, so revoking one doesn't break the others, and a clear name is what an admin will search for in **Settings → Connections**.

[![Notion New personal access token form with Token name, Workspace and Notion API capability](https://storage.ghost.io/c/5c/30/5c30c46b-86a3-4d20-984f-4f6ae8ad1ed2/content/images/2026/11/notion-api-key-native-pat-capabilities-20261121.webp)](https://storage.ghost.io/c/5c/30/5c30c46b-86a3-4d20-984f-4f6ae8ad1ed2/content/images/2026/11/notion-api-key-native-pat-capabilities-20261121.webp?ref=notionsolutions.net)

Name the token, select its workspace and enable the Notion API capability. This example shows the form before a token is created.

### Who can create a personal access token on each plan

Guests and restricted members can't create personal access tokens. Full workspace members can, subject to the workspace's PAT creation policy, and workspace owners always can. The plan sets the default:

__Default PAT creation policy by Notion plan__
| Plan       | Default PAT creation policy          | Admin controls                                                                                          |
| ---------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| Free       | Workspace owners only                | Not configurable                                                                                        |
| Plus       | All workspace members                | Not configurable                                                                                        |
| Business   | Workspace owners only                | Admins can choose Workspace owners only or All workspace members                                        |
| Enterprise | Workspace owners and selected groups | Admins can choose Workspace owners only, Workspace owners and selected groups, or All workspace members |

On Enterprise, if no groups are selected, only workspace owners can create tokens with Notion API access. So if you're a member and the New token option isn't there for you, your role or the workspace policy is the reason. The [API quickstart](https://developers.notion.com/guides/get-started/quick-start?ref=notionsolutions.net) tells Business and Enterprise members to ask a workspace owner to enable it in **Settings → Connections**. If you aren't sure whether you joined as a member or a guest, [the difference between a Notion guest and a member](https://notionsolutions.net/notion-guest-vs-member/) settles that before any plan setting matters.

## How to create an internal connection for team automations

An internal connection works as its own bot user, so its access belongs to the connection and not to whoever set it up. You must be a workspace owner to create one, and every workspace owner can see all internal connections in the Developer portal, including ones other owners created. The [internal connection guide](https://developers.notion.com/guides/get-started/internal-connections?ref=notionsolutions.net) lists the steps:

1. Open the Developer portal and, in the **Build** section of the sidebar, select **Internal connections**.
2. Select **Create a new connection**, enter a name and choose the workspace where the connection can be installed.
3. Open the **Configuration** tab and copy the **API token**.
4. On the same tab, set the capabilities the automation needs, such as reading, updating or inserting content and reading user information.

If you're a member rather than an owner, the work splits here. The connection will run the automation, but an owner decides whether it should exist. Send the owner the connection name you want, the pages it needs and the capabilities, and let them create it.

### Give the connection access to pages

A new internal connection has no page access, and the guide warns that API requests return an error until you grant some. There are two ways to do it:

- **From the Developer portal:** open the connection, select the **Content access** tab, then **Edit access**, and choose the pages and databases.
- **From a Notion page:** open the page, select the **•••** menu in the top-right corner, choose **Connections**, then **\+ Add connection**, search for the connection and confirm it can access the page and its child pages.

Sharing a parent page also shares every child page under it, which is convenient and easy to overdo. I'd share the narrowest parent that holds what the automation touches, such as a single Clients database rather than a teamspace's top page, so a leaked token exposes one database instead of most of the workspace.

[![Notion page connection search showing the search field and available connections](https://storage.ghost.io/c/5c/30/5c30c46b-86a3-4d20-984f-4f6ae8ad1ed2/content/images/2026/11/notion-api-key-native-connection-search-20261121.webp)](https://storage.ghost.io/c/5c/30/5c30c46b-86a3-4d20-984f-4f6ae8ad1ed2/content/images/2026/11/notion-api-key-native-connection-search-20261121.webp?ref=notionsolutions.net)

Search for your internal connection in the page's Connections menu. A PAT does not need this sharing step.

## Public connections: OAuth for apps other people install

If you're building something other people will install in their own workspaces, a pasted key is the wrong model. A [public connection](https://developers.notion.com/guides/get-started/public-connections?ref=notionsolutions.net) uses OAuth 2.0, so every user who authorizes it receives their own access token for their own workspace. In outline:

1. In the Developer portal, under **Build**, select **Connections**, then **Create new connection**, and fill in the name and development workspace, the redirect URIs, the installation scope and the capabilities.
2. The **Configuration** tab then holds the **OAuth client ID**, the **OAuth client secret** and the authorization URL that users visit.
3. A user opens that URL, reviews the capabilities, picks pages in the page picker and approves.
4. Notion redirects to your redirect URI with a temporary code, and your server exchanges that code for an access token.

Choose the installation scope with care. **Any workspace** creates a public integration eligible for Marketplace listing, subject to review. **Or select 1 or more workspaces** creates an OAuth integration limited to those workspaces and ineligible for Marketplace listing. The scope can't be changed after creation. Each workspace member who wants to use the connection has to authorize it individually.

The [Create a token](https://developers.notion.com/reference/create-a-token?ref=notionsolutions.net) endpoint turns up in searches for a Notion API key, but it isn't a way to get one. It's `POST /v1/oauth/token`, the step where a public connection exchanges an authorization code or a refresh token for an access token, authenticating with its client ID and client secret. Notion's OAuth endpoints under `/v1/oauth/*` [send no CORS headers on purpose](https://developers.notion.com/guides/get-started/handling-api-keys?ref=notionsolutions.net), because the exchange needs the client secret and has to run on a server.

## Capabilities: give the key only what the job needs

Capabilities limit what a token can do even on pages it can reach. A connection can combine Read content, Update content and Insert content, add Read comments and Insert comments, and take one of three user information levels: no user information, user information without email addresses, or user information with email addresses. The combinations matter. Notion's [capabilities reference](https://developers.notion.com/reference/capabilities?ref=notionsolutions.net) notes that Update content alone can't create pages, and Insert content alone can create pages but can't read full objects.

The reference's own examples make a good starting point: a connection that brings data into Notion needs Insert content only, one that exports data needs Read content only, and one that updates a property needs Update content only. It adds that fewer capabilities make a workspace admin more likely to install a connection, and users of a public connection have to authenticate again when its capabilities change.

A personal access token is coarser. Its Notion API capability covers reading, creating, updating and searching content in one switch, across everything its creator can open. For a read-only export the whole team depends on, I'd use an internal connection with Read content alone, because it's the narrower credential for that job.

## Where to store a Notion API key

Anyone who holds a token can do whatever its capabilities and page access allow. That's why [Notion's guide to securing API credentials](https://developers.notion.com/guides/get-started/handling-api-keys?ref=notionsolutions.net) keeps tokens out of messages, support requests, issue trackers, source code and configuration files. For local work, put the value in an environment variable. On macOS or Linux:

```
export NOTION_API_KEY=ntn_***
```

In Windows PowerShell:

```
$env:NOTION_API_KEY = "ntn_***"
```

Replace `ntn_***` with your token. Either line lasts only for that terminal session, so run it again when you open a new window. For a project, keep the value in a `.env` file and list that file in `.gitignore` before your first commit:

```
# .env (never commit this file)
NOTION_API_KEY=ntn_***
```

```
# .gitignore
.env
```

Three more rules from the same guide close the usual gaps:

- **Keep tokens out of browser bundles.** The Notion API sends CORS headers, so browser code can call it directly, and build tools copy variables whose names start with `VITE_` or `NEXT_PUBLIC_` into the bundle. Never give a token one of those names, and never ship an internal connection token or a client secret in page source that strangers can load.
- **Use one token per environment.** Separate tokens for development, staging and production mean that revoking the development token leaves production running.
- **Turn on secret scanning.** Enable it in the repository and the CI system, block commits that contain tokens, and alert the token's owner when one is detected.

For a deployed app, move the value into a secret manager, limit who can read production secrets and keep an inventory of each token's owner and purpose. That inventory is what tells you which apps to update when a token has to be replaced.

## How to check that your Notion API key works

The cleanest check is a request that touches none of your pages. Notion's [Retrieve your token's bot user](https://developers.notion.com/reference/get-self?ref=notionsolutions.net) endpoint, `GET /v1/users/me`, returns the bot user behind whatever token you send:

```
curl https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11"
```

The endpoint works for credentials with any content, property or comment capability; user information capabilities on their own don't grant access to it. The endpoint's reference lists `2026-03-11` as the latest API version. A valid token returns a user object, and these fields tell you which key you're holding:

__What the /v1/users/me response tells you__
| Field in the response                     | What it tells you                                                                                                                                |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| object and type                           | "user" and "bot": the token answers as a bot user, and that includes a personal access token                                                     |
| bot.owner.type is "user"                  | The bot acts for a person. For a personal access token, bot.owner.user is the person who created it, which should be you                         |
| bot.owner.type is "workspace"             | The owner is the workspace itself, which the reference describes as a bot for an internal integration, the older name for an internal connection |
| bot.workspace\_name and bot.workspace\_id | The workspace the token belongs to, which catches a token created in the wrong workspace                                                         |

A successful response proves the token is valid and that you sent it correctly. It doesn't prove the token can reach a particular page, so the first real request against your database is the page-access test.

### Error codes when the check fails

Notion's [status code reference](https://developers.notion.com/reference/status-codes?ref=notionsolutions.net) maps each failure to a cause. These are the ones a new key produces:

__Notion API key errors and the fix for each__
| Status | Code                 | What it means                                                                                                                           | What to do                                                                                                                                            |
| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401    | unauthorized         | The bearer token isn't valid; the example message is "API token is invalid."                                                            | Check that you copied the whole value and that the token hasn't expired. A PAT also returns this when the workspace policy stops allowing its creator |
| 400    | missing\_version     | The request has no Notion-Version header                                                                                                | Add \-H "Notion-Version: 2026-03-11"                                                                                                                  |
| 403    | restricted\_resource | The token lacks permission, or the request exceeds a workspace block limit; the message explains which                                  | Read the message, then compare the token's capabilities with what the request does                                                                    |
| 404    | object\_not\_found   | The resource doesn't exist for this token, or it hasn't been shared with the token's owner; the message can include the connection name | For an internal connection, share the page or its parent with the connection. For a PAT, confirm that you can open the page yourself                  |
| 429    | rate\_limited        | The request exceeds the number of requests allowed                                                                                      | Wait for the Retry-After value, then retry                                                                                                            |

For internal and public connections, the Developer portal adds a [Health tab](https://developers.notion.com/guides/manage-connections/connection-health?ref=notionsolutions.net): select the connection, then **Health**. It covers the last 24 hours and updates every hour. Its **Error codes** list shows which codes the connection received, and its **Rate limits** list shows which limits it reached, so you can confirm a fix without digging through logs. Figures that include successful requests are estimates and start with `~`.

## Rotate, refresh or revoke a key

Plan the replacement before you need it. Personal access tokens expire on the date chosen at creation, at most one year out, and Notion's credential guide says to replace long-lived tokens on a schedule and whenever someone with access to them leaves the team. Create the new PAT and update the script before the old one expires.

### If a token was exposed

If a token may have leaked through a commit, a screenshot or a chat message, the guide gives three steps in this order:

1. **Disable the token.** In Notion, go to **Settings** → **Connections** → **Develop or manage connections**, find the connection or personal access token, and select **Refresh** for an internal connection or revoke the personal access token. A PAT can also be revoked from **Personal access tokens** in the Developer portal; create a new one if the tool still needs access.
2. **Update applications.** Replace the old token in every application and environment that used it, test the new one, and remove the old value from configuration files and documentation.
3. **Review activity.** Check recent changes to pages and databases, and look for connections you don't recognize in **Settings** → **Connections**.

For an internal connection, the same refresh is available from the connection's **Configuration** tab in the Developer portal. For help with an exposed token or unauthorized access, the guide points to Notion support.

### Who can revoke a personal access token

- The creator can revoke their own PATs from the Developer portal.
- Workspace admins can revoke any PAT in the workspace from **Settings → Connections → All personal access tokens**. They can also view every PAT, active, expired or revoked, search and filter by name, creator and status, and see who revoked a token.
- Organization owners can list and revoke PATs through the Admin API.

Two rules are easy to miss. Admins can't view or copy another member's token value; only the creator sees it, once, at creation. And if an admin changes the policy so a member is no longer allowed to create PATs with Notion API access, that member's existing tokens return `unauthorized` until the policy allows the member again. A revoked token stops working immediately for every script, tool and Worker that uses it, which is where one token per tool pays off: you revoke one and the rest keep running.

## ntn\_ or secret\_: which prefix is right?

Both prefixes are genuine. Notion's token format notice of September 11, 2024, reproduced in the [notion-sdk-py issue tracker](https://github.com/ramnes/notion-sdk-py/issues/245?ref=notionsolutions.net), says newly generated API tokens use the `ntn_` prefix instead of `secret_` starting September 25, 2024, and that existing `secret_` tokens keep working without changes. The stated reasons are better compatibility with secret scanners and a clearer distinction from other kinds of secrets.

A tutorial that shows the `secret_` prefix is simply older than the change. Don't write code that checks the prefix or matches the token with a regular expression: the same notice warns that the format may change and recommends validating a token with an authenticated request, which is exactly what the `/v1/users/me` check does. Use the token exactly as provided.

## Rate limits that apply to your key

Notion's [request limits](https://developers.notion.com/reference/request-limits?ref=notionsolutions.net) give each connection a fixed budget per 60-second window: 600 requests per minute, an average of 10 per second, on Business and Enterprise workspaces, and 180 requests per minute, an average of 3 per second, on all other plans. The budget can be spent evenly or in a single burst. Querying a data source has its own limit of about 3 requests per second per connection, and a separate per-workspace limit is shared by all connections in the workspace.

Going over any of them returns HTTP 429 with the code `rate_limited` and a `Retry-After` header in seconds. For the per-connection limit that wait is at most 60 seconds; the per-workspace limit can ask for longer than a minute. The JavaScript SDK automatically retries 429 `rate_limited` and 529 `service_overload` responses, but caps `Retry-After` at 60 seconds by default. Its [retry handler](https://github.com/makenotion/notion-sdk-js/blob/main/src/Client.ts?ref=notionsolutions.net) does not distinguish the restricted-access reason within a 429\. For a large import or sync, I would set `retry: false` on the client and let a persistent job queue honor the full interval before retrying, with a retry limit and backoff. If `additional_data.rate_limit_reason` is `public_api_request_blocked`, stop and contact Notion support; retrying will not restore access. The workspace budget is shared with every other connection your team runs.

## Old names you'll see in tutorials

Older tutorials, videos and third-party import guides use Notion's earlier vocabulary, while the current [developer overview](https://developers.notion.com/guides/get-started/overview?ref=notionsolutions.net) distinguishes internal connections, OAuth integrations and public integrations. The Developer portal still uses public connection as a label for a public integration. Use this map to translate older instructions, and follow the meaning when a label in your account reads differently from either column.

__Older Notion API names and their names in the developer docs__
| Name you may see               | Name in Notion's developer docs                                                              |
| ------------------------------ | -------------------------------------------------------------------------------------------- |
| Internal integration           | Internal connection                                                                          |
| Public connection              | Public integration for any workspace; an OAuth integration is limited to selected workspaces |
| Internal Integration Secret    | Internal connection API token, shown as API token on the connection's Configuration tab      |
| Develop or manage integrations | Develop or manage connections                                                                |

### Getting a key for an Anytype import

Import guides from other apps often keep the older wording. Anytype's own [Migrate from Notion guide](https://doc.anytype.io/anytype/data/import-and-export/migrate-from-notion?ref=notionsolutions.net) describes the Notion side like this:

1. In Notion, open **Settings**, then **Connections**, then **Develop or manage integrations**, and create a **New integration** for your workspace with the type set to **Internal**.
2. Under **Capabilities**, select **Read content** and **Read user information**, then **Save changes**.
3. Under **Access**, select the teamspace to import and all of its root pages, then **Update access**.
4. Copy the **Internal Integration Secret**.
5. In Anytype, open your space's settings, select **Import**, choose **Notion**, enter the secret and select **Import data**.

In Notion's current terms that's an internal connection, which means a workspace owner has to create it, and the value you paste is its API token. Anytype documents only this internal route, so that's the one I'd follow. The root-page step matters most: Anytype says pages that weren't connected before the import can go missing or leave broken links, and the fix is to add the missing connection and run the import again. It also lists what changes on the way: user mentions become plain text, date ranges become text, and formulas and summary data arrive as values. If the API import runs into problems, Anytype's fallback is a Markdown & CSV export, which it describes as more lossy.

If you're still choosing where to move, [our guide to Notion alternatives](https://notionsolutions.net/notion-alternatives/) compares Anytype with Obsidian, AppFlowy and AFFiNE for private or offline notes.

## When you don't need an API key at all

Several jobs that seem to need the API already have a route inside Notion:

- **Reacting to a change in a database,** such as setting a status or notifying someone, often fits a button or a database automation. [Buttons versus database automations](https://notionsolutions.net/notion-buttons-vs-automations/) explains which suits a deliberate click and which suits an event, and [planning an automation's trigger, action and exception](https://notionsolutions.net/notion-automations-trigger-action-exception/) shows how to define one before you build it.
- **Collecting responses into a database** works with Notion's own forms and no connector at all; [connecting a form to a Notion database](https://notionsolutions.net/notion-connect-form-to-database/) also compares the outside form tools.
- **Getting data out once** needs an export, not a token. [Exporting a Notion database to CSV](https://notionsolutions.net/notion-export-database/) covers a single table, and [backing up a client project](https://notionsolutions.net/notion-client-project-backup/) covers a full handover archive.

I'd reach for a key only when the work has to run on a schedule outside Notion, pull data from another system, or happen at a volume that clicking can't match.

## My verdict: which key to create today

Use a personal access token for anything that acts as you and runs on your own machine: a script, a notebook or a tool that asks you to paste a token. Use an internal connection for anything the team depends on, because it isn't tied to any workspace member and pages shared with it stay shared when the member who shared them leaves; a PAT loses its access along with its creator. Never paste either one into a chat, a support ticket or a browser bundle, and keep it in an environment variable or in a `.env` file that `.gitignore` excludes. For experiments, choose the 7-day or 30-day expiration and let the token run out on its own.

Start small. Create the token, run the `/v1/users/me` check, and confirm the owner and workspace in the response before you build anything on it. Then make your first real call with [the guide to creating a page with the Notion API](https://notionsolutions.net/notion-api-create-page/), which picks up where this check ends.