Create a token

Creates an access token that a third-party service can use to authenticate with Notion.

POST /v1/oauth/token

TypeScript SDK

JavaScript

import { Client } from "@notionhq/client"

const notion = new Client()

const response = await notion.oauth.token({
  client_id: process.env.OAUTH_CLIENT_ID,
  client_secret: process.env.OAUTH_CLIENT_SECRET,
  grant_type: "authorization_code",
  code: "abc123-authorization-code",
  redirect_uri: "https://example.com/callback"
})

200

{
  "access_token": "<string>",
  "token_type": "<string>",
  "refresh_token": "<string>",
  "bot_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workspace_icon": "<string>",
  "workspace_name": "<string>",
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "owner": {
    "type": "<string>",
    "user": {
      "type": "<string>",
      "person": {
        "email": "<string>"
      },
      "name": "<string>",
      "avatar_url": "<string>",
      "id": "<string>",
      "object": "<string>"
    }
  },
  "duplicated_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

For step-by-step instructions on how to use this endpoint to create a public connection, check out the Authorization guide. To walkthrough how to create tokens for Link Previews, refer to the Link Previews guide.

Redirect URI requirements for public connections

The redirect_uri is a required field in the request body for this endpoint if:

• the redirect_uri query parameter was set in the Authorization URL provided to users, or;
• there are more than one redirect_uris included in the connection’s settings under OAuth Domain & URIs.

In most cases, the redirect_uri field is required.

This field is not allowed in the request body if:

• there is one redirect_uri included in the connection’s settings under OAuth Domain & URIs, and the redirect_uri query parameter was not included in the Authorization URL.

Learn more in the public connection section of the Authorization Guide.

Note: Each Public API endpoint can return several possible error codes. To see a full description of each type of error code, see the Error codes section of the Status codes documentation.

Authorizations

Authorization · string · header · required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Headers

Notion-Version · enum<string> · required

The API version to use for this request. The latest version is 2026-03-11.

Available options: 2026-03-11

Body

application/json

Option 1

Option 2

grant_type · string · required

Allowed value: "authorization_code"

code · string · required

redirect_uri · string

external_account · object

Show child attributes

Response

200

application/json

access_token · string · required

token_type · string · required

Allowed value: "bearer"

refresh_token · string | null · required

bot_id · string<uuid> · required

workspace_icon · string | null · required

workspace_name · string | null · required

workspace_id · string<uuid> · required

owner · User · object · required

User

Workspace

Show child attributes

duplicated_template_id · string<uuid> | null · required

request_id · string<uuid>