fix(backend): expose externalAccountId on ExternalAccount resource

[jacekradko]

The backend ExternalAccount.id is the idn_ identification id for Google and Facebook accounts, so handing it to users.deleteUserExternalAccount() (which wants the eac_ id) returns a 404. This adds an optional externalAccountId that carries the eac_ value.

The part worth knowing is why it's optional. The Backend API only returns external_account_id for Google and Facebook accounts, where id is the idn_ value. Every other provider already returns id as the eac_ id and no external_account_id. So the deletable id is externalAccountId ?? id, never externalAccountId on its own, and the JSDoc plus changeset say as much. The getUser fixture now carries both a google_account and a generic external_account entry so the test asserts both shapes.

This is an alternative to #8982, which mapped the same field but typed it as a required string and pointed callers at externalAccountId directly, which would 404 for every non-Google/Facebook account.

Fixes #7936
Fixes #7584

[changeset-bot]

🦋 Changeset detected

Latest commit: afef28f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 10 packages

Name	Type
@clerk/backend	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 25, 2026 12:49pm
swingset	Ready	Preview, Comment	Jun 25, 2026 12:49pm

[coderabbitai]

📝 Walkthrough

Walkthrough

ExternalAccount now carries an optional externalAccountId from external_account_id, while keeping existing id and identificationId mapping. Tests, fixtures, and a changeset were updated to reflect provider-specific external account IDs.

Changes

External account ID mapping

Layer / File(s)	Summary
External account contract packages/backend/src/api/resources/JSON.ts, packages/backend/src/api/resources/ExternalAccount.ts	ExternalAccountJSON adds external_account_id, and ExternalAccount stores it as externalAccountId while reading it from data.external_account_id.
Provider mapping coverage packages/backend/src/api/__tests__/factory.test.ts, packages/backend/src/api/resources/__tests__/ExternalAccount.test.ts, packages/backend/src/fixtures/user.json, .changeset/backend-external-account-id.md	Tests and fixtures assert the provider-specific mapping for id, identificationId, and externalAccountId, and the changeset records the patch release.

🎯 2 (Simple) | ⏱️ ~10 minutes

🐰 I hopped through IDs, both new and old,
idn_ and eac_ now shine like gold.
Fixtures bounce, tests nibble neat,
The mapping now feels snug and sweet.
Hoppity hop—what a tidy treat!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly states the backend change to expose externalAccountId on ExternalAccount and matches the PR scope.
Linked Issues check	✅ Passed	The PR adds optional externalAccountId mapping and tests so getUser returns the eac_ ID needed by deleteUserExternalAccount().
Out of Scope Changes check	✅ Passed	The fixture, tests, and changeset all support the ExternalAccount ID fix and don't introduce unrelated functionality.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8995

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8995

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8995

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8995

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@8995

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@8995

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@8995

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8995

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8995

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8995

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8995

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8995

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8995

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8995

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8995

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8995

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8995

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8995

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8995

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8995

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8995

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8995

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8995

commit: afef28f

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-25T12:50:47.727Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	0
🟡 Non-breaking changes	1
🟢 Additions	2

🤖 This report was reviewed by claude-sonnet-4-6.

---

@clerk/backend

Current version: 3.8.3
Recommended bump: MINOR → 3.9.0

🟡 Non-breaking Changes (1)

Modified: ExternalAccount.undefined

// ... 12 unchanged lines elided ...
      phoneNumber: string | null, 
      publicMetadata: (Record<string, unknown> | null) | undefined, 
      label: string | null, 
-     verification: Verification | null);
+     verification: Verification | null, 
+     externalAccountId?: string | undefined);

Static analyzer: Modified constructor ExternalAccount.undefined: Optional parameter externalAccountId was added

🤖 AI review (confirmed) (95%): Adding an optional parameter externalAccountId? at the end of a constructor signature is non-breaking: existing callers omit it and continue to compile correctly.

🟢 Additions (2)

Added: ExternalAccount.externalAccountId

+ readonly externalAccountId?: string | undefined;

Added property ExternalAccount.externalAccountId

Added: ExternalAccountJSON.external_account_id

+ external_account_id?: string;

Added property ExternalAccountJSON.external_account_id

---

Report generated by Break Check

_{Last ran on afef28f.}