Authentication

Every REST API request requires an API key in the Authorization header.

Authorization: Bearer pp_example_replace_with_your_key

API keys

Create and revoke keys from Developer Access in Paperpin. Keys belong to the current tenant and inherit that tenant's resource access. Paperpin stores a SHA-256 hash, never the plaintext value. API keys authorize the REST API only.

The plaintext key is displayed only once when it is created. Copy it immediately and store it in a secret manager. Version 1 supports up to three active keys per tenant.

Keys that are revoked or expired cannot authenticate. Successful REST authentication updates the key's last-used time.

MCP OAuth

Remote MCP clients authenticate through OAuth 2.1 Authorization Code with S256 PKCE. Paperpin API keys, Supabase session tokens, ID tokens, and MCP session identifiers do not authorize MCP access.

See MCP connection for discovery, consent, permissions, and revocation.

First REST request

curl https://paperpin.io/api/v1/groups \
  -H "Authorization: Bearer pp_example_replace_with_your_key"

Tenant isolation

All API operations are scoped to the authenticated tenant. A resource ID from another tenant is treated as missing.

Error responses

REST errors use this stable format:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key."
  }
}

See errors and rate limits for response codes and retry behavior.