fix(connectors): read Notion identity from the token response

Merged
HA
2mo ago
+383-58

Summary

Notion needs two connectors, not one. This PR splits them and fixes the identity probe that kept the MCP one from ever connecting.

  • notion_mcp (new) is what the Notion plugin binds to: the client: "dynamic" method against mcp.notion.com, with identity read from the OAuth token response instead of a second HTTP request.
  • notion keeps its name and every row it already has, and is now described as what those rows actually hold — a static oauth2 app on api.notion.com, which is what /integrations/notion mints and what Notion triggers run on.
  • identity.url becomes optional; a url-less probe reads its $. paths out of the token payload.
  • First-party installs resolve their connector from the published manifest rather than the copy stored at install time, so existing Notion plugin installs actually move to notion_mcp.

Why / Context

The probe was pointed at the wrong audience

Connecting Notion sent you through consent and back to /connect/notion with the button still reading Connect. That looked like a token problem — the callback maps every exception to ?error=token_exchange_failed — but the token exchange succeeds. Production logs show the real failure, reproduced across three separate attempts:

[connectors/notion] callback failed: Error: Connector "notion" identity probe failed: 401

connectors.json probed https://api.notion.com/v1/users/me, but the access token is issued by the MCP authorization server at mcp.notion.com for resource https://mcp.notion.com/mcp. Notion's REST API rejects that audience.

Confirmed with a live token obtained by hand against mcp.notion.com — same token, same moment:

RequestResult
GET api.notion.com/v1/users/me401 {"code":"unauthorized","message":"API token is invalid."}
POST mcp.notion.com/mcp (control)200 MCP initialize succeeds

The probe was also reading $.bot.workspace_id, which is absent from this response shape, so it would have failed at the accountId guard even if the audience had matched.

This has never worked. The connector was added in 55390500e and untouched since; it is also the only client: "dynamic" connector, so nothing else exercises this path.

Fixing that alone would have broken Notion triggers

Raised in review, and the reason this PR grew. Two different Notion token types were sharing one connections row:

  • /integrations/notion stores an api.notion.com token. Every existing notion row is one of these, including the ones #7675 backfilled.
  • /connect/notion stores an mcp.notion.com token.

Both upsert the same row, because the user-scope conflict target is (org, connector, user, externalAccountId) and externalAccountId is workspace_id in both. The moment the MCP connect starts succeeding, onConflictDoUpdate replaces the trigger's token — and the webhook fetches (normalizeNotionDelivery.ts) and trigger-options.ts start getting 401s. Worse, isPermanentNotionError classifies a 401 as permanent, so those deliveries are skipped, not retried.

One token cannot serve both audiences: mcp.notion.com returns 403 restricted_resource for a Notion API token, and api.notion.com returns 401 for an MCP token. Linear avoids this because mcp.linear.app accepts ordinary Linear tokens.

Two things were already broken today, independent of the probe fix, and the split fixes both:

  • a user connected only for triggers shows as connected in the Notion plugin, and every tool call ships their API token to mcp.notion.com;
  • uninstalling the Notion plugin disconnects every notion connection, including the one triggers use.

How It Works

Identity from the token response

mcp.notion.com exposes no userinfo endpoint (/userinfo, /oauth/userinfo, /v1/userinfo, /me all 404). Its only identity source is /introspect, which is unusable from probeIdentity for two independent reasons:

  1. It requires application/x-www-form-urlencoded, but index.ts always sends JSON.stringify(probe.body). Verified: a JSON body returns 400 "Content-Type must be application/x-www-form-urlencoded".
  2. It needs the token in the body, and probe.body is never templated — only url and headers pass through resolveConnectorTemplate. Putting the token in the query string does not work either; Notion ignores query params entirely (401 "Client ID is required" even with client_id present).

No second request is needed, because the token response already carries everything:

access_token, bot_id, email_domain, expires_in, refresh_token, resource,
scope, token_type, user_id, workspace_icon, workspace_id, workspace_name

So the identity probe is now a union: either a probe with a url (unchanged, every other connector) or a url-less one that reads the same $. paths out of ConnectorTokens.raw. A union rather than an optional url because a url-less probe that still declared method/headers/body used to parse fine and silently ignore them.

Two connectors, one slug that never changes meaning

A slug is a connector's only identifier — stored as text in connections.connector, named by connector.slug in plugin manifests, hardcoded in trigger code. So nothing is renamed:

  • notion keeps meaning the api.notion.com token, which is what every saved row already holds. It gains requires_env, token_url, and identity paths matching that response shape ($.workspace_id, $.workspace_name, $.owner.user.id, $.owner.user.name).
  • notion_mcp is new and has no rows yet, because that flow never completed.
  • No data migration, and connections.connector is text(), so no enum change either.

Existing installs follow the published manifest

plugin_installs.manifest is a copy taken at install time and rewritten only on reinstall, so repointing plugin.json would leave every existing install resolving notion. installConnector() resolves a first-party install against firstPartyManifest(pluginName) and falls back to the stored copy for everything else. It is used everywhere the routing decision is made:

  • resolve-target.ts — which connection a tool call runs under;
  • plugins.uninstall — which rows get disconnected, so the trigger's notion row survives;
  • plugins.list / plugins.connections.list — which connection the UI calls this plugin's.

Third-party installs are unaffected: their manifest copy is still the only thing that decides.

Testing

bun run typecheck, bun run lint, bun run check:i18n, bunx sherif, bun run check:plugins and the @superset/trpc (347) and @superset/shared (1108) suites all pass locally.

New tests:

  • connectors.test.ts — a url-less probe reads the token response with globalThis.fetch stubbed to throw, and fails loudly when no token payload is passed.
  • manifest.test.ts — installConnector follows the published manifest for a first-party install, keeps the stored copy for a third-party one, and falls back when the name is not published.
  • plugins.test.ts (new) — plugins.uninstall disconnects the notion_mcp row and leaves the trigger's notion row alone; it also leaves the connector alone while another install still claims it, and never touches another member's connection.

Manual QA Checklist

Not yet run — needs preview or prod, since both flows need real Notion credentials.

The split

  • Connecting from /connect/notion_mcp and from /integrations/notion produces two separate connections rows
  • A Notion trigger still fires after the MCP connection exists
  • A Notion plugin tool call works under the notion_mcp credential
  • Uninstalling the Notion plugin disconnects only the notion_mcp row

Happy path

  • Connect completes and the button flips to connected
  • The connection shows the Notion workspace name as its account label

Regression (other connectors take the unchanged path)

  • Linear connect still completes (static client, requires_env)
  • Slack connect still completes (static client, requires_env)
  • An api_key connector still completes (e.g. Sentry) — the probe path is untouched

Error handling

  • Reconnecting an already-linked Notion workspace still surfaces account_already_linked

Design Decisions

  • Token-sourced identity instead of making /introspect work: the latter needs two changes (form encoding and body templating), adds a network round-trip per connect, and returns no workspace_name. Both routes require a schema change, so this is strictly the smaller one.
  • A new slug rather than a connectors table: the slug stays the key and nothing ever has to be renamed, which is what keeps the migration empty.
  • installConnector rather than rewriting stored manifests: a backfill would have to run before the manifest ships and would still race new installs. Resolving at read time is correct from the first request.

Known Limitations

  • No user label on the MCP connection — Notion's token response carries user_id but no user name field, so user.label is null.
  • The api_key path (router/connectors/index.ts) passes no token payload, so a url-less identity there throws a clear error. Unreachable today, but it fails loudly rather than silently if one is added.

Follow-ups

  • Replace the bespoke /api/integrations/notion/* routes with the generic connect flow, keeping the upsertIdentity call for me mentions. The notion connector is now described well enough for that to be a deletion rather than a rewrite.
  • The callback collapses every exception into ?error=token_exchange_failed (callback/[connector]/route.ts). A 401 identity probe reporting as a token-exchange failure is what disguised this bug; surfacing the real cause is a separate change.
  • deploy-preview.yml passes no NOTION_* secrets and the Preview GitHub environment has none, so the older /api/integrations/notion/* routes are dead on preview deploys.

Risks / Rollout

  • Risk: low. Other connectors take the identical pre-existing code path. notion rows are untouched. The one broad failure mode — the registry failing zod at import — is loud and immediate, and CI parses it.
  • Rollout order matters: the API must ship before anyone reinstalls the plugin, which is automatic here since both land in the same commit.
  • Rollback: revert. No data migration, no persisted state, no feature flag. A published plugin version is additive; reverting the manifest points installs back at notion.

Summary by cubic

Fixes the Notion connector, which has never completed a connection: its identity probe hit Notion's REST API with an MCP-issued token (401) and read response fields absent from that response shape. Also splits Notion into two connectors so a working MCP connection can't overwrite the token Notion triggers run on.

  • Makes identity.url optional; url-less probes read identity paths directly from the OAuth token response, which already carries workspace_id, workspace_name, and user_id.
  • Adds notion_mcp for the dynamic client against mcp.notion.com; notion keeps its name and rows and is now described as the static api.notion.com oauth2 app it already held. No data migration.
  • installConnector resolves first-party installs against the published manifest rather than the copy stored at install time, so existing Notion installs move to notion_mcp.
  • Uninstalling the plugin now disconnects only the notion_mcp row and leaves the connection alone while another install or member still claims it.
  • All other connectors keep their url and take the unchanged fetch path.

Summary by CodeRabbit

  • Improvements
    • Improved connector identity detection during sign-in and authorization.
    • Connectors can now retrieve account details directly from authorization responses when a separate identity lookup is unavailable.
    • Updated Notion connections to use workspace and user identifiers from the authorization response; they no longer make an additional user lookup or show the user’s name in identity details.
    • Improved plugin connection matching, including for Notion. Uninstalling a plugin no longer disconnects a connection still used by another installation or member.