Authentication

All API requests are authenticated with a Bearer token in the Authorization header:

Authorization: Bearer YOUR_TOKEN

Two kinds of token are accepted, and they behave identically once issued:

Token	How you get it	Use it for
API key	Generated in your Paperpile account settings	Scripts and integrations acting as you
OAuth 2.0 access token	Issued by the authorization-code flow below	Applications acting on behalf of other users

Either token grants access to your personal library and all shared libraries you have access to. The same tokens authenticate the MCP endpoint.

OAuth 2.0

Paperpile supports the authorization-code flow with PKCE, and dynamic client registration, so an app can onboard without a manually provisioned client.

Discover the endpoints from the authorization server metadata rather than hard-coding them — it is served at /.well-known/oauth-authorization-server (and /.well-known/openid-configuration) on the Paperpile API host:

https://stage-api.paperpile.com/.well-known/oauth-authorization-server

It advertises the authorization_endpoint, token_endpoint, and registration_endpoint, along with the supported parameters:

Metadata	Value
response_types_supported	code
grant_types_supported	authorization_code
code_challenge_methods_supported	S256
token_endpoint_auth_methods_supported	none, client_secret_basic, client_secret_post

PKCE is required, and S256 is the only supported challenge method.

Clients that need to discover which authorization server protects a resource can read the Protected Resource Metadata at /.well-known/oauth-protected-resource on the platform host — this is how MCP clients bootstrap.

Scopes

Each token has a scope that determines which operations it can perform:

Scope	Allowed methods
read	GET, HEAD, OPTIONS
read_write	All of the above, plus POST, PUT, PATCH, DELETE

A read-scoped token used on a write request (POST, PUT, PATCH, DELETE) is rejected with 403 Forbidden (authorization_error / forbidden).

Errors

Situation	Status	type / code
Missing Authorization header or malformed Bearer	401	authentication_error / unauthorized
Token not recognized	401	authentication_error / unauthorized
Token scope too low for the method	403	authorization_error / forbidden
Add-on type token	403	authorization_error / forbidden

Add-on tokens (issued for in-app add-ons) are not accepted on this API and always return 403.