Notion

Read and write the Notion pages and databases a user shares with your app.

Docs & Knowledge
OAuth 2.0
Works on Free plan
Bundled in Kirak
Maintained by Kirak

How to use it

This profile ships with Kirak. Add "integrations" to modules in kirak.json, then name the profile as below. There is nothing to download, and a copy in your project's integrations/ folder is an error.

Environment variables

Variable	Holds
`KIRAK_INTEGRATION_NOTION_CLIENT_SECRET`	The OAuth client secret from the vendor's console. Secret: keep it out of kirak.json and out of source control.
`KIRAK_AUTH_ENCRYPTION_KEYS`	Encrypts stored tokens. Shared by every integration; the module refuses to start without it.

The names follow the integration's name in kirak.json (notion here). Name it something else, such as notion_sales, and the variables change to match.

Redirect URL

Register this as the redirect (callback) URL in the vendor's console, with your app's address in place of <your-app> (the base_url in kirak.json):

https://<your-app>/integrations/notion/callback

How to get your keys

Open Notion’s integrations page and create a new integration of type Public.
Set the redirect URI to https://<your-app>/integrations/notion/callback.
Choose the integration’s capabilities (read content, update content, …). Notion sets the access here, not through scopes.
Copy the OAuth client ID and the client secret.
Put the client ID in kirak.json as integrations.providers.notion.client_id, and the client secret in the environment as KIRAK_INTEGRATION_NOTION_CLIENT_SECRET. Never put the secret in kirak.json.

The vendor's own guide · Instructions out of date? ·Suggest an edit

kirak.json

{
  "integrations": {
    "providers": {
      "notion": {
        "type": "oauth2",
        "profile": "notion",
        "client_id": "your-client-id"
      }
    }
  }
}

Merged into the profile: scope replaces the profile's default scopes. Notion sets access when you register the app, so there is no scope.

Good to know

The scopes are not sent: the integration's capabilities are set in Notion's settings when the integration is registered.
The token request is a JSON body with HTTP Basic credentials. A refresh returns a new access token and a new refresh token.
The lifetime of an access token is not stated in the docs read; the stored expiry stays empty, and a 401 triggers a refresh.
The Notion-Version header value is not from the token page; confirm it against Notion's versioning page before a release.
PKCE is not documented for this integration type, so it is off.

Example calls

POST /search: Search pages the integration can see

Help improve this profile

Report a problem ·Suggest an edit to profile.json ·Add a profile ·Vendor docs the profile was checked against

Product names and logos are trademarks of their respective owners. Their use does not imply endorsement. To ask for this icon to be removed, email trademark@kirak.io.