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

Summary by CodeRabbit

• Bug Fixes

  • Improved how external account IDs are returned for linked social accounts, so account deletion and related actions use the correct identifier.
  • Kept existing behavior for other providers while making the ID mapping more consistent.

• Tests

  • Added coverage for provider-specific external account ID handling to verify the updated behavior.

[changeset-bot]

🦋 Changeset detected

Latest commit: 8f9546d

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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 9ec22195-d655-48ad-8a14-442afebb4238

📥 Commits

Reviewing files that changed from the base of the PR and between afef28f and 8f9546d.

📒 Files selected for processing (6)

• .changeset/backend-external-account-id.md
• packages/backend/src/api/__tests__/factory.test.ts
• packages/backend/src/api/resources/ExternalAccount.ts
• packages/backend/src/api/resources/JSON.ts
• packages/backend/src/api/resources/__tests__/ExternalAccount.test.ts
• packages/backend/src/fixtures/user.json

✅ Files skipped from review due to trivial changes (2)

• .changeset/backend-external-account-id.md
• packages/backend/src/api/tests/factory.test.ts

🚧 Files skipped from review as they are similar to previous changes (4)

• packages/backend/src/api/resources/ExternalAccount.ts
• packages/backend/src/api/resources/tests/ExternalAccount.test.ts
• packages/backend/src/api/resources/JSON.ts
• packages/backend/src/fixtures/user.json

---

📝 Walkthrough

Walkthrough

ExternalAccount now carries an optional externalAccountId from external_account_id, while preserving existing id and identificationId mapping. Tests, fixtures, and a changeset were updated for 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main backend ExternalAccount change and is concise.
Linked Issues check	✅ Passed	The PR exposes optional externalAccountId while preserving id behavior, matching the linked bug fixes and compatibility requirements.
Out of Scope Changes check	✅ Passed	All edits support the ExternalAccount ID fix through code, tests, fixtures, and a changeset; no unrelated changes are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ 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: 8f9546d

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-26T12:40:31.956Z

Summary

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

Warning
5 breaking change(s) detected - Major version bump required

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

🔴 Breaking changes index (5)

Every breaking change, up front. Full diffs are in the package sections below.

Package	Subpath	Change
@clerk/shared	./types	OrganizationDomainOwnershipVerification.status
@clerk/shared	./types	OrganizationDomainOwnershipVerificationJSON.status
@clerk/shared	./types	OrganizationDomainOwnershipVerificationStatus
@clerk/shared	./types	OrganizationDomainOwnershipVerificationStrategy
@clerk/shared	./types	OrganizationDomainVerificationStatus

---

@clerk/shared

Version: 4.22.0 → 4.21.0
Recommended bump: MAJOR

Subpath ./types

🔴 Breaking Changes (5)

Changed: OrganizationDomainOwnershipVerification.status

- status: OrganizationDomainOwnershipVerificationStatus;
+ status: OrganizationDomainVerificationStatus;

Static analyzer: Breaking change in property OrganizationDomainOwnershipVerification.status: Type changed: import("@clerk/shared").OrganizationDomainOwnershipVerificationStatus → import("@clerk/shared").OrganizationDomainVerificationStatus

🤖 AI review (confirmed) (85%): The status field on OrganizationDomainOwnershipVerification changed from OrganizationDomainOwnershipVerificationStatus ('expired'|'unverified'|'verified') to OrganizationDomainVerificationStatus ('unverified'|'verified'), dropping 'expired'; consumers reading this output field that branch on 'expired' will hit an unhandled case or a type-check error.

Migration: Update any switch/if statements that handle the 'expired' status on OrganizationDomainOwnershipVerification.status to use OrganizationDomainVerificationStatus ('unverified' | 'verified') and remove the 'expired' branch.

Changed: OrganizationDomainOwnershipVerificationJSON.status

- status: OrganizationDomainOwnershipVerificationStatus;
+ status: OrganizationDomainVerificationStatus;

Static analyzer: Breaking change in property OrganizationDomainOwnershipVerificationJSON.status: Type changed: import("@clerk/shared").OrganizationDomainOwnershipVerificationStatus → import("@clerk/shared").OrganizationDomainVerificationStatus

🤖 AI review (confirmed) (85%): Same narrowing as b73ffcd5d145 applied to OrganizationDomainOwnershipVerificationJSON.status; the 'expired' variant is removed, breaking consumers that read or switch on this JSON field.

Migration: Update consumers reading OrganizationDomainOwnershipVerificationJSON.status to only handle 'unverified' | 'verified' and remove handling of 'expired'.

Changed: OrganizationDomainOwnershipVerificationStatus

- type OrganizationDomainOwnershipVerificationStatus = 'unverified' | 'verified' | 'expired';

Static analyzer: Removed type alias OrganizationDomainOwnershipVerificationStatus

🤖 AI review (confirmed) (95%): The exported type alias OrganizationDomainOwnershipVerificationStatus has been removed entirely; any consumer that imported or referenced it will fail to compile.

Migration: Replace usages of OrganizationDomainOwnershipVerificationStatus with OrganizationDomainVerificationStatus ('unverified' | 'verified').

Changed: OrganizationDomainOwnershipVerificationStrategy

- type OrganizationDomainOwnershipVerificationStrategy = 'txt' | 'legacy' | 'manual_override' | 'parent_domain';
+ type OrganizationDomainOwnershipVerificationStrategy = 'txt' | 'legacy' | 'manual_override';

Static analyzer: Breaking change in type alias OrganizationDomainOwnershipVerificationStrategy: Type changed: 'legacy'|'manual_override'|'parent_domain'|'txt' → 'legacy'|'manual_override'|'txt'

🤖 AI review (confirmed) (90%): The 'parent_domain' variant was removed from OrganizationDomainOwnershipVerificationStrategy; consumers that read this output field and handle 'parent_domain' (e.g., in a switch statement) will have a type error with exhaustiveness checks, and runtime values of 'parent_domain' are no longer typed.

Migration: Remove 'parent_domain' from any exhaustive checks or type annotations referencing OrganizationDomainOwnershipVerificationStrategy.

Changed: OrganizationDomainVerificationStatus

- type OrganizationDomainVerificationStatus = 'unverified' | 'verified' | 'failed' | 'expired';
+ type OrganizationDomainVerificationStatus = 'unverified' | 'verified';

Static analyzer: Breaking change in type alias OrganizationDomainVerificationStatus: Type changed: 'expired'|'failed'|'unverified'|'verified' → 'unverified'|'verified'

🤖 AI review (confirmed) (90%): The 'expired' and 'failed' variants were removed from OrganizationDomainVerificationStatus; consumers reading output fields typed with this union that handle those variants will get type errors under strict/exhaustive checks.

Migration: Remove 'expired' and 'failed' branches from any exhaustive switch/if statements over OrganizationDomainVerificationStatus.

🟡 Non-breaking Changes (1)

Modified: __internal_LocalizationResource

// ... 1297 unchanged lines elided ...
        domainCard: {
          badge__verified: LocalizationValue;
          badge__unverified: LocalizationValue;
-         badge__expired: LocalizationValue;
          verifiedAtLabel: LocalizationValue<'date'>;
-         expiredAtLabel: LocalizationValue<'date'>;
-         expiredLabel: LocalizationValue;
-         verifyAgainButton: LocalizationValue;
          removeButtonTooltip__lastVerifiedDomain: LocalizationValue;
          removeButtonTooltip__lastVerifiedDomainActive: LocalizationValue;
          txtRecord: {
// ... 639 unchanged lines elided ...

Static analyzer: Breaking change in type alias __internal_LocalizationResource: Type changed: {locale:string;maintenanceMode:import("@clerk/shared").LocalizationValue;roles:{[r:string]:import("@clerk/shared").Loca… → {locale:string;maintenanceMode:import("@clerk/shared").LocalizationValue;roles:{[r:string]:import("@clerk/shared").Loca…

🤖 AI review (reclassified as non-breaking) (55%): The diff elides 1867 vs 1863 lines suggesting ~4 lines were removed, but __internal_LocalizationResource is used only as an input to DeepLocalizationWithoutObjects via LocalizationResource extends DeepPartial<...>, meaning consumers supply partial overrides; removing optional keys from an output/template type they partially implement is unlikely to break well-typed consumers. Without the full diffed lines it is impossible to be certain, so confidence is low.

---

@clerk/backend

Version: 3.8.4 → 3.8.3
Recommended bump: MINOR

🟡 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 the constructor signature does not break existing callers, since all prior call sites remain valid without providing the new argument.

🟢 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

---

@clerk/ui

Version: 1.23.0 → 1.22.0
Recommended bump: MINOR

Subpath ./internal

🟡 Non-breaking Changes (1)

Modified: ElementsConfig

// ... 490 unchanged lines elided ...
    configureSSOVerifyDomainErrorSubtitle: WithOptions;
    configureSSOVerifyDomainList: WithOptions;
    configureSSOVerifyDomainSuggestion: WithOptions;
-   configureSSOVerifyDomainCard: WithOptions<'verified' | 'unverified' | 'expired'>;
-   configureSSOVerifyDomainCardBadge: WithOptions<'verified' | 'unverified' | 'expired'>;
+   configureSSOVerifyDomainCard: WithOptions<'verified' | 'unverified'>;
+   configureSSOVerifyDomainCardBadge: WithOptions<'verified' | 'unverified'>;
    configureSSOVerifyDomainCardRemoveButton: WithOptions;
    configureSSOVerifyDomainCardTxtRecord: WithOptions;
    configureSSOVerifyDomainCardTxtRecordValue: WithOptions;
-   configureSSOVerifyDomainCardExpired: WithOptions;
    configureSSOEmailVerificationForm: WithOptions<string>;
    configureSSOEmailVerificationIcon: WithOptions<string>;
    configureSSOEmailVerificationTitle: WithOptions<string>;
// ... 51 unchanged lines elided ...

Static analyzer: Breaking change in type alias ElementsConfig: Type changed: {button:import("@clerk/ui").~WithOptions<string>;input:import("@clerk/ui").~WithOptions;checkbox:import("@clerk/ui").~W… → {button:import("@clerk/ui").~WithOptions<string>;input:import("@clerk/ui").~WithOptions;checkbox:import("@clerk/ui").~W…

🤖 AI review (reclassified as non-breaking) (85%): The elided diff shows 473 vs 472 lines, indicating one property was removed from ElementsConfig; however, ElementsConfig is used only as the key source for the Elements output type alias (a mapped type consumers read, not construct), so removing a key from the config only narrows the set of selectors available — existing consumer code reading Elements values is unaffected, and no consumer constructs an ElementsConfig object directly.

---

Report generated by Break Check

_{Last ran on 8f9546d.}

[jacekradko]

Building on @VihaanAgarwal's original fix in #8982. Added him as co-author on the squash.