PaperClipAI/docs/oauth-integrations.md

OAuth Integrations — Operator Guide

Overview

Paperclip ships with a built-in OAuth backbone supporting GitHub, Notion, Slack, Linear, Atlassian, Google Workspace, and Microsoft Graph. Each provider is opt-in: a provider is registered iff its client_id and client_secret env vars are both set at startup. Providers with missing credentials are skipped with a WARN log and never appear at Settings → Connections.

Setup per provider

For each provider you want to enable:

1. Register an OAuth app in the provider's developer console.

2. Configure the redirect URI as: ${PAPERCLIP_PUBLIC_URL}/api/oauth/callback/<provider-id>

3. Set both env vars before starting the server:

   Provider	client_id env	client_secret env
   github	GITHUB_OAUTH_CLIENT_ID	GITHUB_OAUTH_CLIENT_SECRET
   notion	NOTION_OAUTH_CLIENT_ID	NOTION_OAUTH_CLIENT_SECRET
   slack	SLACK_OAUTH_CLIENT_ID	SLACK_OAUTH_CLIENT_SECRET
   linear	LINEAR_OAUTH_CLIENT_ID	LINEAR_OAUTH_CLIENT_SECRET
   atlassian	ATLASSIAN_OAUTH_CLIENT_ID	ATLASSIAN_OAUTH_CLIENT_SECRET
   google-workspace	GOOGLE_OAUTH_CLIENT_ID	GOOGLE_OAUTH_CLIENT_SECRET
   microsoft-graph	MICROSOFT_OAUTH_CLIENT_ID	MICROSOFT_OAUTH_CLIENT_SECRET

4. Restart the server.

5. Tiles for that provider appear at Settings → Connections. Admins can connect.

Adding a custom provider

The bundled YAML configs live at server/oauth-providers/. To add a custom provider, drop a YAML file in that directory (or set PAPERCLIP_OAUTH_PROVIDERS_DIR to a directory of your own and put the YAML there — entries from that directory are loaded after and merged with the bundled configs). Set the corresponding client_id and client_secret env vars and restart the server. See server/oauth-providers/github.yaml for the canonical example.

For providers with non-standard response shapes (Slack's team block, Microsoft's id_token claim parsing, etc.), add a TypeScript shape module under server/src/oauth/shapes/ and wire it from the YAML's shape: field. See server/src/oauth/shapes/slack.ts for the canonical example.

Plugin-contributed providers

Plugins can ship OAuth providers via the oauthProviders block in the plugin manifest. See packages/plugins/sdk/src/define-oauth-provider.ts for the helper, and the plugin developer docs for the manifest schema. A YAML entry with the same provider id always wins; plugin contributions for a duplicate id are skipped with a WARN log.

Operations

• Refresh worker: runs every 60s, leader-elected via Postgres advisory lock. No additional config needed.
• Token storage: OAuth tokens live in company_secrets / company_secret_versions, encrypted via the configured SecretProvider.
• Logs: all OAuth code paths emit structured pino logs with component=oauth. Token material is never logged — access_token, refresh_token, id_token, code, code_verifier, and client_secret are redacted at the logger level.
• Metrics: oauth_refresh_total, oauth_refresh_duration_seconds, oauth_connections_by_status (Prometheus, existing pattern).

Troubleshooting

• "Provider isn't configured": check both env vars are set; restart to pick up changes.
• "Refresh stalled": check last_error on the connection row; usually provider-side (network blip). Manual Refresh now from the UI clears the backoff.
• "Account mismatch": user authorized a different account than the existing connection. Disconnect first, then reconnect.

Known limitations

• Linear accountInfo uses https://api.linear.app/oauth/userinfo (Linear's OIDC userinfo endpoint). If Linear changes that endpoint, the YAML at server/oauth-providers/linear.yaml will need to update or grow a custom shape module.
• Per-tenant rate limit on POST /oauth/connect/:providerId is 50 requests per 5 minutes (state-row flood guard). This is in addition to the existing per-user limit.
• Refresh worker leader-election uses pg_try_advisory_xact_lock inside a single transaction so the lock is released automatically at COMMIT/ROLLBACK regardless of which pool connection the underlying postgres-js client picked up. Multi-process deployments coordinate naturally through the shared lock.
• mark-revoked middleware is wired in app.ts and reads a Bearer run-JWT via verifyLocalAgentJwt. The endpoint returns 401 without a valid JWT carrying an oauth.connectionIds claim, 403 when the claim doesn't include the requested connection, 204 on success.
• GitHub upstream revocation is best-effort. GitHub's /applications/{client_id}/grant endpoint requires DELETE and a JSON body ({"access_token": "..."}), not RFC-7009's POST + form-encoded shape that revokeUpstreamToken uses. The upstream revoke call therefore always fails for GitHub — the local disconnect cleanup path swallows the error and proceeds, so the user's local state ends up correct, but the GitHub grant remains valid until natural expiry or until the user revokes it via the GitHub UI. A follow-up PR will add a per-provider revokeStyle field to handle non-RFC-7009 providers.