Authentication and Scopes

Understand Bearer tokens, scopes, public routes, and common authentication failures.

Send an access token with every protected V2 request by using the Authorization header.

Authorization: Bearer <token>

Do not send tokens in query strings or request bodies. Public OpenAPI routes are the only V2 routes that do not require a token.

Public and Protected Routes

Route	Behavior
`GET /v2/openapi.json`	Returns the current OpenAPI document.
`GET /v2/openapi/meta`	Returns metadata such as `etag`, generated time, and path count.
All other `/v2/*` routes	Require `Authorization: Bearer <token>`.

Token type	Identity returned by `GET /v2/users/me`
Integration token	`bot_user` for the integration.
OAuth token	`bot_user` with the scopes authorized for the token.

A request can still fail after token validation if the workspace plan does not allow public API access. In that case the API returns 403 forbidden.

Scope	Description
`pages.read`	Read page metadata and properties.
`pages.write`	Create, update, delete, and upload files for page workflows.
`blocks.read`	Read blocks and block children.
`blocks.write`	Append, update, and delete blocks.
`databases.read`	Read databases and query database records.
`databases.write`	Create, update, and delete databases.
`users.read`	Read user profiles.
`users.email.read`	Return `person.email` in user profile responses.
`search.read`	Run keyword or semantic search.

401 unauthorized: missing token, malformed Authorization header, expired token, or invalid token.
403 forbidden: token is valid but missing the required scope, the resource is not accessible, or the workspace plan blocks the API capability.