From 374f251c58480562400e21c4d5e54e89b7bcb5d2 Mon Sep 17 00:00:00 2001
From: Jibaru <ignacioruedaboada@hotmail.com>
Date: Thu, 5 Feb 2026 14:06:55 -0500
Subject: [PATCH] feat(backend,clerk-js): Add providerUserId field to
 ExternalAccount

Add providerUserId as a new field to the ExternalAccount resource to
provide a clearer way to access the unique user ID from OAuth
providers. This field is now the preferred way to retrieve provider
user identifiers.

The existing externalId field is deprecated in favor of providerUserId
for better clarity and consistency across the API. The externalId field
remains available but is marked with @deprecated JSDoc annotation to
guide developers toward the new field.
---
 .changeset/legal-crabs-shout.md                             | 6 ++++++
 packages/backend/src/api/resources/ExternalAccount.ts       | 6 ++++++
 .../src/core/resources/__tests__/ExternalAccount.test.ts    | 4 ++++
 3 files changed, 16 insertions(+)
 create mode 100644 .changeset/legal-crabs-shout.md

diff --git a/.changeset/legal-crabs-shout.md b/.changeset/legal-crabs-shout.md
new file mode 100644
index 00000000000..1f694546d75
--- /dev/null
+++ b/.changeset/legal-crabs-shout.md
@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/backend': minor
+---
+
+Add `providerUserId` field to `ExternalAccount` resource as the preferred way to access the unique user ID from the OAuth provider. The existing `externalId` field is now deprecated in favor of `providerUserId` for better clarity and consistency across the API.
diff --git a/packages/backend/src/api/resources/ExternalAccount.ts b/packages/backend/src/api/resources/ExternalAccount.ts
index a4fcd8bbb80..a623a7f8a51 100644
--- a/packages/backend/src/api/resources/ExternalAccount.ts
+++ b/packages/backend/src/api/resources/ExternalAccount.ts
@@ -16,12 +16,17 @@ export class ExternalAccount {
      * The provider name (e.g., `google`).
      */
     readonly provider: string,
+    /**
+     * The unique ID of the user in the provider.
+     */
+    readonly providerUserId: string,
     /**
      * The identification with which this external account is associated.
      */
     readonly identificationId: string,
     /**
      * The unique ID of the user in the provider.
+     * @deprecated Use providerUserId instead
      */
     readonly externalId: string,
     /**
@@ -70,6 +75,7 @@ export class ExternalAccount {
     return new ExternalAccount(
       data.id,
       data.provider,
+      data.provider_user_id,
       data.identification_id,
       data.provider_user_id,
       data.approved_scopes,
diff --git a/packages/clerk-js/src/core/resources/__tests__/ExternalAccount.test.ts b/packages/clerk-js/src/core/resources/__tests__/ExternalAccount.test.ts
index 9c59639cdb1..5e01de7b539 100644
--- a/packages/clerk-js/src/core/resources/__tests__/ExternalAccount.test.ts
+++ b/packages/clerk-js/src/core/resources/__tests__/ExternalAccount.test.ts
@@ -9,6 +9,8 @@ describe('External account', () => {
     const externalAccountJSON = {
       object: 'external_account',
       id: targetId,
+      provider_user_id: 'test_provider_user_id',
+      identification_id: 'test_identification_id',
     };
 
     // @ts-ignore
@@ -35,6 +37,8 @@ describe('External account', () => {
       object: 'external_account',
       id: targetId,
       deleted: true,
+      provider_user_id: 'test_provider_user_id',
+      identification_id: 'test_identification_id',
     };
 
     // @ts-ignore