feat(auth): Add support for VERIFY_AND_CHANGE_EMAIL out-of-band links

[jagadeesh545]

Discussion

Fixes #949

This pull request introduces the ability to generate out-of-band (OOB) email action links for the VERIFY_AND_CHANGE_EMAIL flow, mirroring the Node.js SDK feature. This enables a secure "change email" flow where the verification link is sent to the current address, protecting accounts from unauthorized email changes during hijacked sessions.

Testing

• Added unit tests in tests/test_user_mgt.py and tests/test_tenant_mgt.py to verify the request payload maps new_email correctly and validates required parameters.
• Added integration tests in integration/test_auth.py and integration/test_tenant_mgt.py to ensure end-to-end functionality against a real Firebase project.
• Verified all existing unit and integration tests pass.

API Changes

• Added 'VERIFY_AND_CHANGE_EMAIL' to VALID_EMAIL_ACTION_TYPES.
• Added generate_verify_and_change_email_link(email, new_email, action_code_settings=None, app=None) to the public auth module.
• Added the corresponding method to the auth Client instance.
• Updated the internal UserManager.generate_email_action_link to accept new_email.

Context Sources Used:

• id: firebase-admin-python

Manual Testing

firebase-admin-python % python
Python 3.12.13 (main, Mar  7 2026, 17:21:21) [Clang 14.0.0 (clang-1400.0.29.202)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
Cmd click to launch VS Code Native REPL
>>> import firebase_admin
>>> from firebase_admin import credentials, auth
>>> cred = credentials.Certificate('cert.json')
>>> firebase_admin.initialize_app(cred)
<firebase_admin.App object at 0x108e2d9a0>
>>> user = auth.create_user(email='test.old.email@example.com', password='testPassword123!', email_verified=True)
>>> print("User created with UID:", user.uid)
User created with UID: ORs8I3zQ5uaNawU08WATZVRpEne2
>>> link = auth.generate_verify_and_change_email_link('test.old.email@example.com', 'test.new.email@example.com')
>>> print("\nClick this link to verify and change the email:")

Click this link to verify and change the email:
>>> print(link)
https://my-test-project-e9a7b.firebaseapp.com/__/auth/action?mode=verifyAndChangeEmail&oobCode=LN6KwORzL53UN2lz_KcyC0kvTjb8gkpg2ezfX1TSZmUAAAGd9lTxSA&apiKey=redacted&lang=en
>>> auth.delete_user(user.uid)
>>> exit()
firebase-admin-python % 

[gemini-code-assist]

Code Review

This pull request introduces the generate_verify_and_change_email_link functionality to the Firebase Admin Python SDK, enabling the generation of links for email verification and change flows. The changes span the Auth client, user management logic, and utility constants, and are accompanied by extensive unit and integration tests. Reviewer feedback includes a suggestion to improve the robustness of the internal link generation method by validating that the new_email parameter is used exclusively with the appropriate action type, as well as a request for PEP 8 compliant formatting in the test suite.

[lahirumaramba]

@jagadeesh545 Thank you for your contribution! We will review this and follow up on the process for adding a new feature. I noticed that an API key was exposed in the PR description (which I have now redacted). If this API key doesn't have restrictions or is attached to other Google services, please revoke it to prevent unauthorized access.

[jagadeesh545]

Thank you @lahirumaramba. The API key is for a dummy test project and I deleted it now.