ENG-2694: Add fides_external_id option to FidesJS SDK to provide a custom ID on preferences

[NevilleS]

Ticket ENG-2694

Description Of Changes

Add support for an optional fides_external_id in FidesJS so customers can pass a custom user ID that is sent with privacy-preferences and notices-served API calls and stored in the consent cookie. The option can be set via init options, overrides (query param, cookie, window), and in the Privacy Center via FIDES_EXTERNAL_ID env and the /fides.js API.

Fides.setIdentity() helper: Customers can set identity after init via Fides.setIdentity({ external_id: "user-123" }). Only external_id is supported; reserved keys (e.g. fides_user_device_id) and verified keys (email, phone_number) throw. Empty or whitespace-only external_id throws (omit the key to leave identity unchanged). Values are trimmed before saving. Init treats empty/whitespace fides_external_id as not set, consistent with setIdentity. Identity key constants are centralized in cookie.ts (FIDES_* prefixed).

Code Changes

• Add fidesExternalId to FidesJS type definitions, consent constants (override validation), and init defaults
• Persist and read external_id in cookie identity in getOrMakeFidesCookie / makeFidesCookie / makeDefaultIdentity
• Add FIDES_EXTERNAL_ID to Privacy Center settings, env loading, and fides.js API config
• Document fides_external_id in FidesOptions docs and add Cypress tests for external_id in consent banner flows
• setIdentity: Add Fides.setIdentity(identity) in consent-types, set-identity module (validation, trim, empty/whitespace reject), init-utils wiring; JSDoc and generated Fides.md; unit tests (incl. empty string, whitespace-only, trim); Cypress tests (setIdentity then save, validation errors, empty string, GPC edge case)
• Init/cookie alignment: makeDefaultIdentity and getOrMakeFidesCookie treat empty/whitespace fidesExternalId as not set; use ?? for device-id fallback; FidesOptions docs note empty/whitespace behavior

Steps to Confirm

1. Load a page with FidesJS and fides_external_id set via override or init; confirm privacy-preferences and notices-served requests include the id and the consent cookie stores it.
2. After init, call Fides.setIdentity({ external_id: "user-456" }) then save preferences; confirm the id is in the API request. Call setIdentity({ external_id: "" }) and confirm it throws; omit the key and confirm identity is unchanged.

Pre-Merge Checklist

• Issue requirements met
• All CI pipelines succeeded
• CHANGELOG.md updated
  • Add a db-migration This indicates that a change includes a database migration label to the entry if your change includes a DB migration
  • Add a high-risk This issue suggests changes that have a high-probability of breaking existing code label to the entry if your change includes a high-risk change (i.e. potential for performance impact or unexpected regression) that should be flagged
  • Updates unreleased work already in Changelog, no new entry necessary
• UX feedback:
  • All UX related changes have been reviewed by a designer
  • No UX review needed
• Followup issues:
  • Followup issues created
  • No followup issues
• Database migrations:
  • Ensure that your downrev is up to date with the latest revision on main
  • Ensure that your downgrade() migration is correct and works
    • If a downgrade migration is not possible for this change, please call this out in the PR description!
  • No migrations
• Documentation:
  • Documentation complete, PR opened in fidesdocs
  • Documentation issue created in fidesdocs
  • If there are any new client scopes created as part of the pull request, remember to update public-facing documentation that references our scope registry
  • No documentation updates required

[vercel]

Deployment failed with the following error:

You must set up Two-Factor Authentication before accessing this team.

View Documentation: https://vercel.com/docs/two-factor-authentication

[NevilleS]

some changes needed to tidy this up

[vercel]

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

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
fides-plus-nightly	Ignored	Preview	Feb 14, 2026 3:57pm
fides-privacy-center	Ignored		Feb 14, 2026 3:57pm

[NevilleS]

missed one more unneeded change

[NevilleS]

Self review notes

[greptile-apps]

Greptile Overview

Greptile Summary

Added support for fides_external_id option in FidesJS SDK, allowing customers to provide a custom user ID that is included in privacy-preferences and notices-served API calls and stored in the consent cookie.

Key changes:

• Added fidesExternalId field to FidesInitOptions interface and Identity type as optional fields
• Implemented makeDefaultIdentity() helper function to generate identity objects with optional external_id
• Updated makeFidesCookie() and getOrMakeFidesCookie() to accept and handle fidesExternalId parameter
• Added logic to preserve existing external_id from cookies when not explicitly provided, and update it when a new value is provided
• Added override validation for fides_external_id with regex /.+/ requiring non-empty strings
• Comprehensive test coverage including edge cases (undefined identity, empty strings, preservation of existing values)
• Added Cypress e2e tests verifying external_id is sent correctly in API calls
• Updated documentation with clear examples of usage

Implementation notes:

• The external_id is only set when fidesExternalId is a non-null, non-undefined value (empty strings are rejected)
• When fidesExternalId is not provided, existing external_id values from the cookie are preserved
• The fides_user_device_id continues to be generated and included alongside external_id to maintain per-device tracking

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation is clean, well-tested, and follows existing patterns in the codebase. The feature adds optional functionality without breaking existing behavior. Test coverage is comprehensive including edge cases, and the logic properly handles null/undefined values to prevent data corruption.
• No files require special attention

Important Files Changed

Filename	Overview
clients/fides-js/src/lib/consent-types.ts	Added fidesExternalId field to FidesInitOptions and Identity type; clean type additions with proper optional handling
clients/fides-js/src/lib/cookie.ts	Implemented external_id handling in cookie operations; logic properly handles setting and preserving external_id
clients/fides-js/src/lib/consent-constants.ts	Added validation config for fides_external_id override with appropriate regex requiring non-empty values
clients/fides-js/tests/lib/cookie.test.ts	Comprehensive test coverage for external_id functionality including edge cases like undefined identity and empty strings
clients/privacy-center/cypress/e2e/fides-js/consent-banner.cy.ts	Added Cypress e2e tests verifying external_id is correctly sent in privacy-preferences and notices-served API calls

_{Last reviewed commit: 3899a21}

[greptile-apps]

_{11 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[gilluminate]

Looks good! tested locally and it works well. Just one clarification question and good to go!

[NevilleS]

Updated the PR description to include the Fides.setIdentity() helper and related behavior (empty/whitespace validation, trim, init alignment, identity constants).

[gilluminate]

Approved with nit-picks. No blockers though. 👍