Skip to content

fix(connectors): send Ahrefs client credentials in the token request body - #9826

Merged
Kitenite merged 1 commit into
mainfrom
kitenite/fix/ahrefs-token-exchange
Nov 16, 2026
Merged

Kitenite merged 1 commit into
mainfrom
kitenite/fix/ahrefs-token-exchange

Conversation

@Kitenite

@Kitenite Kitenite commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Problem

Ahrefs connect has never succeeded. The OAuth round trip completes, then the token exchange fails and the desktop shows "Could not connect Ahrefs. Try again."

Production evidence (Vercel api-paradev, 2026-11-16, five attempts by one customer):

[connectors/ahrefs_mcp] callback failed: Error: Connector "ahrefs_mcp" token exchange failed: 400 {"error":"invalid_grant"}
  • The authorize request and the token request use the same redirect URI. In the same period, other dynamic-client connectors (Linear, Notion, PostHog, Circleback) connected on the same host.
  • Ahrefs metadata advertises no token_endpoint_auth_methods_supported, so pickAuthMethod registered the client as client_secret_basic. Ahrefs accepts that and returns base64 ids and secrets that contain +, / and =.
  • exchangeCode then sent Authorization: Basic base64(id:secret) without form-encoding the id and secret, and sent no client_id in the body.
  • Ahrefs' OAuth guide says to send client_id and client_secret in the form body. It does not mention Basic.

Fix

A dynamic-client method can now set token_request_auth_method in connectors.json. Before this PR, only static clients used that field. When a dynamic method sets it:

  • registration asks for that method instead of the method picked from the metadata;
  • token requests (code exchange and refresh) use that method, including for a client already stored under another method;
  • a new connect skips a stored client registered with another secret method and registers a new client. No migration is needed: the old client_secret_basic rows stay, and new connects stop using them.

ahrefs_mcp sets client_secret_post.

notion_mcp had token_request_auth_method: client_secret_basic. Before this PR the code ignored that field for dynamic clients, so the PR removes it, and Notion keeps its current behavior. (Notion uses a client id metadata document and has no secret to send.)

Probes (public endpoints, throwaway clients, no secrets logged)

  • Registering with token_endpoint_auth_method: client_secret_post works: Ahrefs echoes client_secret_post and returns a secret. It grants only authorization_code, not refresh_token.
  • POST https://ahrefs.com/oauth/token with no client id anywhere returns No client_id. With only a Basic header, Ahrefs gets past that check, so it does read Basic.
  • With a fake code, every variant returns invalid_grant (body or Basic, correct or wrong secret, unknown client). Ahrefs checks the code before the client, so a fake code cannot tell the variants apart.

Not confirmed: whether body credentials are what fixes invalid_grant for a real code. One possible cause is the + in the Basic value being decoded as a space. Only a real authorization can confirm this.

Not changed

  • Form-encoding the Basic id and secret (RFC 6749 §2.3.1) for every connector. Encoding changes every id or secret that contains reserved characters. A server that does not decode them (some do not) would break connectors that work today, and I cannot check each server. I left it as a possible follow-up.
  • Ahrefs identity. The identity is $.token_type, so every Ahrefs connection has the account id Bearer. Connect works, because user connections are keyed by user. But grantSharedWithAnotherConnection will treat any two users' Ahrefs connections as sharing a grant. I need a real token response to find a better field.
  • Ahrefs refresh. Ahrefs issues no refresh token. When a token expires (if expires_in is returned), the connection is marked needs_reauth, which is expected.
  • Ahrefs MCP auth. The MCP endpoint (https://api.ahrefs.com/mcp/mcp) accepts Authorization: Bearer: a bogus token gets Access denied: MCP token is invalid. I could not test a valid token.

Tests

client-identity.test.ts adds tests for Ahrefs:

  • registration asks for client_secret_post;
  • a new connect replaces a stored client_secret_basic client;
  • the code exchange sends client_id and client_secret in the body, with no Basic header;
  • a code issued to an already-stored basic client is still redeemed with credentials in the body.

Three of these tests fail without the fix.

Manual test (needs an Ahrefs Lite+ account)

  1. Deploy this branch to a preview API, or use production after merge.
  2. In the desktop app, install the Ahrefs plugin and click Connect.
  3. Approve on app.ahrefs.com. The connect should finish with no "Could not connect Ahrefs" error.
  4. In Vercel logs, check that /api/connectors/callback/ahrefs_mcp returns no token exchange failed.
  5. Ask an agent to run an Ahrefs tool (for example public-domain-rating-free for a domain). It should return data, not Access denied.
  6. Send the token response's keys (not their values) so we can replace the $.token_type identity.

End-to-end evidence (local stack, real Ahrefs servers) — 2026-11-16

Setup: local API (:8261) and web (:8260) from this branch, on this workspace's own Neon branch (non-primary, branched from production today). Outbound fetches from the API were logged by a --require preload, and secrets, codes, verifiers and tokens are redacted to their length. The browser was a separate Chrome, driven over CDP and signed in as the local dev admin. The desktop dev app (renderer :8265) received the deep links. A token stand-in on 127.0.0.1:8299 replaced https://ahrefs.com/oauth/token only for the runs marked "stand-in".

1. Connect up to the Ahrefs authorize page (no stored client)

GET /api/connectors/ahrefs_mcp/connect?organizationId=…&method=oauth2&plugin=ahrefs returns 302 to the real Ahrefs authorize page ("Sign in to Ahrefs").

POST https://api.ahrefs.com/mcp/register
{"client_name":"Paradev","client_uri":"https://superset.sh",
 "redirect_uris":["http://localhost:8261/api/connectors/callback/ahrefs_mcp"],
 "grant_types":["authorization_code"],"response_types":["code"],"application_type":"web",
 "token_endpoint_auth_method":"client_secret_post","scope":"apiv3-mcp"}
-> 200 {"client_id":"xvrWAsmlnBf5O3mDDmgd7A==","client_secret":"<redacted:24>",
        "token_endpoint_auth_method":"client_secret_post","grant_types":["authorization_code"],…}

302 https://app.ahrefs.com/web/oauth/authorize?client_id=xvrWAsmlnBf5O3mDDmgd7A%3D%3D
   &redirect_uri=http%3A%2F%2Flocalhost%3A8261%2Fapi%2Fconnectors%2Fcallback%2Fahrefs_mcp
   &state=<450 chars>&response_type=code&resource=https%3A%2F%2Fapi.ahrefs.com%2F
   &code_challenge=<43 chars>&code_challenge_method=S256&scope=apiv3-mcp

Ahrefs accepts client_secret_post and the http://localhost redirect URI at registration. The authorize page shows the same sign-in page for this client, for a redirect URI that was never registered, and for an unknown client. So Ahrefs checks the redirect URI only after sign-in, and that part needs a real account.

2. The token request the fix sends (stand-in), compared with Ahrefs' OAuth guide

POST /oauth/token   content-type: application/x-www-form-urlencoded   accept: application/json   (no Authorization header)
grant_type=authorization_code  client_id=xvrWAsmlnBf5O3mDDmgd7A==  client_secret=<redacted:24>
redirect_uri=http://localhost:8261/api/connectors/callback/ahrefs_mcp  code=<redacted>  code_verifier=<redacted:43>
resource=https://api.ahrefs.com/
Guide field Sent
grant_type=authorization_code ✅
client_id (same as step 1) ✅ body
redirect_uri (same as step 1) ✅ identical string
code ✅
code_verifier ✅ 43 chars
client_secret (web apps) ✅ body
form-urlencoded body ✅
(not in guide) resource (RFC 8707)

The same request on main, captured the same way: authorization: Basic base64(gI876bzjGDGeugiFQw4PJw==:<redacted>), and the body has no client_id and no client_secret.

Replay of this request shape against the real https://ahrefs.com/oauth/token with a fake code: 400 {"error":"invalid_grant"}. It is the same with no resource, with a wrong secret, with an unknown client, and with an unknown extra field. So Ahrefs ignores extra fields, and a fake code cannot tell the auth variants apart.

3. Stored-client paths (real DB rows, real Ahrefs registration)

Path Client used How it authenticates
(a) no stored client registers a new client as client_secret_post body
(b) only a stored client_secret_basic client (real Ahrefs registration, scopes {apiv3-mcp}) skips it and registers a new client_secret_post client; a second connect reuses that one with 0 registrations body
(c) callback for the client recorded in the signed state (stand-in) xvrW… from the state body; the callback ends at ?connected=1; the connection row has oauth_client_id=xvrW…, external_account_id=Bearer, no refresh token, expires_in applied
(c′) signed state recording the stored basic client (an authorize that started before deploy) CNZf… (basic row) body, no Authorization header; ends at ?connected=1

4. Regression: other dynamic connectors, main vs this branch

Connector main: registration method → authorize this branch
linear_mcp client_secret_post → mcp.linear.app/authorize client_secret_post → same
notion_mcp client_secret_post → mcp.notion.com/authorize client_secret_post → same
notion_mcp with the old token_request_auth_method: client_secret_basic line kept — client_secret_basic

On main the Notion line had no effect for dynamic clients. Under this PR it would switch Notion to Basic, so removing it keeps Notion as on main. (In production, Notion uses a client id metadata document over https, so it has no secret and the field does not apply there either.)

5. Negative paths

Case Callback redirect What the user sees
user denies (error=access_denied) web /connect/ahrefs_mcp?error=oauth_denied web: no toast (see below)
invalid_grant (real Ahrefs, fake code) /plugins/ahrefs?error=token_exchange_failed → desktop deep link desktop: "Could not connect Ahrefs. Try again."
invalid_client (stand-in) same as above same toast; the stored client row is deleted (forgetClient)
state cookie missing web /connect/ahrefs_mcp?error=invalid_state web: no toast
state older than 10 min web /connect/ahrefs_mcp?error=invalid_state, no token request web: no toast

Desktop toasts were checked by opening the dev app's own deep link (superset-<workspace>://plugins/ahrefs?…). Results: token_exchange_failed shows "Could not connect Ahrefs. Try again.", oauth_denied shows "You declined the Ahrefs authorization request.", invalid_state shows "That Ahrefs sign-in link expired. Try connecting again.", and connected=1 shows "Connected Ahrefs".

Found along the way, not changed by this PR:

  • /connect/<slug>?error=… and ?connected=1 on web show no toast for any connector (Linear included). The effect runs, because the query is cleared, but nothing is rendered.
  • A plugin connect that fails in resolveCallback (deny, bad state) goes to web /connect/<slug>, not to the desktop plugin page.
  • In local dev, web hands off to superset://, but the dev desktop app registers superset-<workspace>://.

6. Plugin proxy and disconnect

With the plugin installed and the stand-in connection stored, tools/call through /mcp/plugins/superset/ahrefs sends Authorization: Bearer <stored token> to https://api.ahrefs.com/mcp/mcp. Ahrefs answers Access denied: MCP token is invalid, as expected for a fake token. connectors.disconnect marks the row disconnect_reason=user, and the proxy then tells the agent to open the connect URL.

Still unconfirmed

A real code exchange, a real token, and a real tool call. These need an Ahrefs account to sign in and approve.

…body

A dynamic-client method can now declare token_request_auth_method. Registration
uses it, token requests honor it even for a client stored under another method,
and a new connect registers afresh instead of reusing such a client. Ahrefs
declares client_secret_post, as its OAuth guide asks. Notion's declaration was
ignored for dynamic clients until now, so it is removed to keep Notion as is.
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

Connector-declared OAuth token authentication methods now take precedence during client registration. Stored-client lookup checks compatibility with the declared method. Ahrefs uses client_secret_post, and Notion no longer declares an authentication method.

Changes: OAuth authentication methods

Layer / File(s) Summary
Declare and select the authentication method
packages/shared/src/connectors/connectors.json, packages/trpc/src/lib/connectors/client-identity.ts
Notion no longer declares client_secret_basic, and Ahrefs declares client_secret_post. Registration uses a declared method when present; otherwise, it retains the server-supported method selection.
Match stored clients by authentication method
packages/trpc/src/lib/connectors/client-identity.ts
Stored-client lookup checks the declared method. A stored basic or post client is excluded when its method conflicts with the declaration.
Verify and document the authentication flow
packages/trpc/src/lib/connectors/client-identity.test.ts, docs/plugins.md
Tests cover Ahrefs registration, replacing a stored basic-auth client, and token exchange with credentials in the request body. The documentation describes method selection and stored-client reuse.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Possibly related PRs

  • ParadevAI/Paradev#9203: Introduced the stored-client selection logic that this pull request updates to check compatibility with the declared token authentication method.

Suggested reviewers: harshithmullapudi

Merge Risk: Minimal · up to fb456

Ahrefs connections now send client credentials in the token request body, which is what Ahrefs' OAuth guide documents. Whether Ahrefs accepts this for every previously stored client was not confirmed against the live service, so check a real Ahrefs connection after release. No concrete defect was found in the change.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title uses conventional commit format and names the main change: Ahrefs token requests now send client credentials in the body. The raw summary confirms the connectors.json, client-identity.ts, an…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description check Passed The description follows the repository template's main sections: it has a problem and fix section (What & why), a detailed testing section with probes, end-to-end evidence and a manual test plan (How …
Full details: Title check

Explanation

The title uses conventional commit format and names the main change: Ahrefs token requests now send client credentials in the body. The raw summary confirms the connectors.json, client-identity.ts, and test changes center on this. The title is specific and matches the changeset, and the PR objectives state the same fix.

Full details: Description check

Explanation

The description follows the repository template's main sections: it has a problem and fix section (What & why), a detailed testing section with probes, end-to-end evidence and a manual test plan (How I tested it), and it links the issue context. It does not include the Checklist section from the template. The checklist items (conventional commit title, bun run lint and typecheck passing, maintainer edits checkbox, CLA signature) are not addressed in the description. The description is substantive and specific, with the problem, the fix, the scope of unchanged behavior, and tests, so the omission is non-critical. Fixes are linked to PR #9826 context but the description does not reference an issue number, which the template asks for when one exists.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 3d03e857-b740-4fed-8e3c-1f138d66fab5
Commits

Reviewing files that changed from the base of the PR and between 3975eb1 and fb456d2.

Files selected for processing: 4

  • docs/plugins.md
  • packages/shared/src/connectors/connectors.json
  • packages/trpc/src/lib/connectors/client-identity.test.ts
  • packages/trpc/src/lib/connectors/client-identity.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

🧹 Preview Cleanup Complete

The following preview resources have been cleaned up:

  • ✅ Neon database branch

Thank you for your contribution! 🎉

@expo

expo Bot commented Nov 16, 2026

Copy link
Copy Markdown

Preview update published for development build 7786fa53 (fingerprint c2f25cad550c). Open the build on your phone and scan:

Update group 3ec0c7fc

@Kitenite
Kitenite merged commit ed1858d into main Nov 16, 2026
20 checks passed

This branch was previously deployed

1 inactive deployment
preview — fb456d24 Deployed Nov 16, 2026 by Kitenite via Cleanup Preview Resources #5663
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant