Notion OAuth Setup | Share to Board™ Docs

Production endpoints

Use	Value
OAuth start URL	`https://sharetoboard.com/notion/oauth/start`
OAuth start (mobile deep-link return)	`https://sharetoboard.com/notion/oauth/start?mobile=1`
Redirect URI (set in Notion integration)	`https://sharetoboard.com/notion/oauth/callback`
Mobile app return URI	`sharetoboard://oauth/notion`
Refresh endpoint	`POST https://sharetoboard.com/notion/oauth/refresh`
Required Notion-Version header	`2025-09-03`

Start OAuth (Web) Start OAuth (Mobile)

Server environment requirements

Variable	Required	Purpose
`NOTION_CLIENT_ID`	Yes	OAuth client ID used for authorize + token exchange.
`NOTION_CLIENT_SECRET`	Yes	OAuth client secret used server-side for token exchange/refresh.
`NOTION_REDIRECT_URI`	Optional	Override callback URI. If unset, runtime host resolves to `/notion/oauth/callback`.

Do not ship NOTION_CLIENT_SECRET in mobile builds. Keep token exchange and refresh server-side only.

Setup sequence

1. Configure integration

Create a public Notion integration and add the exact redirect URI: https://sharetoboard.com/notion/oauth/callback. Enable capabilities required by your workspace policy for reading and writing database content.

2. Connect database access

Open the source Inbox database page in Notion, then use Share > Add connections and connect the installed integration. If this step is skipped, Notion API reads can return 404 even with a valid database ID.

3. Save app settings

In Share to Board Notion settings, set Access Token, optional Refresh Token, Database ID, and Notion-Version 2025-09-03, then tap Verify access.

Required Inbox database schema

Property names are case-sensitive. Required options must exist exactly as listed.

Property	Type	Required options / notes
Title	title	Required
CaptureID	rich_text	Required
Source	select	Must include `SharetoBoard`
Status	select	Must include `Inbox`, `Routed`, `Error`
Type	select	Must include `Audio`, `Text`, `Transcript`, `Link`, `Image`, `Video`

Direct API verification

Use a direct Notion API read to separate permission issues from app configuration issues:

curl -sS -D - -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Notion-Version: 2025-09-03" "https://api.notion.com/v1/databases/YOUR_DATABASE_ID"

HTTP 200: token + permissions + database ID are valid.
HTTP 404: integration is not connected to the source database page, or database ID is wrong.
HTTP 401/403: token invalid/expired or install/scopes are incorrect.

Refresh contract

Endpoint	Method	Request body	Response fields
`/notion/oauth/refresh`	`POST`	`{ "refresh_token": "..." }`	`access_token`, `refresh_token`, `expires_in`, `workspace_id`, `workspace_name`, `bot_id`

Troubleshooting map

Error	Cause	Fix
`Missing properties: ...`	Schema property names do not match expected names.	Add required properties exactly: `Title`, `CaptureID`, `Source`, `Status`, `Type`.
`Source select must include SharetoBoard`	`Source` select missing required option.	Add select option `SharetoBoard`.
`Status select must include Inbox, Routed, Error`	`Status` options incomplete.	Add all three required options.
`Type select is missing required options`	`Type` options incomplete.	Add `Audio`, `Text`, `Transcript`, `Link`, `Image`, `Video`.
`notion_http_404...`	Integration lacks access to source database page.	Share the source database page with the integration again.
`notion_http_400...`	Usually malformed ID/version mismatch.	Recheck database ID and keep Notion-Version at `2025-09-03`.

No version downgrade is required for this flow. Share to Board supports Notion 2025-09-03 with data source-aware behavior. OAuth callback pages are no-store and token values are not persisted server-side.

Notion OAuth setup for Share to Board.