auth0/auth0-php

This is the first stable release of v9. It introduces breaking changes to the Management API, and two behavior changes to the Authentication API. Please consult the v9 Migration Guide and UPGRADE.md for detailed upgrade instructions.

🚀 What's New

This release marks a major milestone for the Auth0 PHP SDK. The Management API client has been completely rewritten using the Fern code generation tool, built directly from the Auth0 OpenAPI specification. This delivers complete, always-up-to-date API coverage with full type safety.

✨ Highlights

• 🏗️ Auto-generated Management API - Rebuilt from the Auth0 OpenAPI spec using Fern, ensuring complete endpoint coverage and consistency with the API
• 🔒 Strongly-typed requests & responses - No more associative arrays or manual JSON decoding. Every request parameter and response field is a typed PHP object with IDE autocompletion
• 📄 Built-in pagination - Pager<T> implements IteratorAggregate, automatically fetching pages as you iterate with foreach
• 🔑 Automatic token management - New ManagementClient wrapper handles OAuth 2.0 client credentials grant, token caching (PSR-6), and custom token providers out of the box
• ⚡ Built-in retry middleware - Automatic retries for rate-limited (429) responses
• 🛡️ Exception-driven error handling - Non-2xx responses throw Auth0ApiException with status code and response body, replacing manual status code checks
• 🔁 Custom Token Exchange - New Authentication::customTokenExchange() and Auth0::loginWithCustomTokenExchange() methods

🔄 What's Changed

The Management API has breaking changes:

The Authentication API is largely unchanged, with two behavior changes:

• client_id, response_type, and response_mode can no longer be overridden through the $params argument on Auth0::login(), Auth0::signup(), Auth0::handleInvitation(), Authentication::getLoginLink(), and the Pushed Authorization Request flow. They are always resolved from your SdkConfiguration
• Auth0::handleBackchannelLogout() now stores cache entries with the configured relative expiry (backchannelLogoutExpires, default 30 days) instead of an absolute timestamp. If you ran a persistent backchannel logout cache on 8.10.0 or later, flush it once after upgrading

📦 Installation

composer require auth0/auth0-php

🔧 Quick Start

use Auth0\SDK\API\Management\Wrapper\ManagementClient;
use Auth0\SDK\API\Management\Wrapper\ManagementClientOptions;
use Auth0\SDK\API\Management\Users\Requests\ListUsersRequestParameters;

$client = new ManagementClient(new ManagementClientOptions(
    domain: 'tenant.auth0.com',
    clientId: 'CLIENT_ID',
    clientSecret: 'CLIENT_SECRET',
));

// List users with automatic pagination
$pager = $client->users->list(new ListUsersRequestParameters([
    'perPage' => 50,
    'includeTotals' => true,
]));

foreach ($pager as $user) {
    echo $user->getEmail();
}

📚 Resources

• v9 Migration Guide (v8 -> v9)
• Examples
• API Reference

Full Changelog

Note: As this is a major release it is recommended to understand the Breaking Changes section before upgrading. The v9 Migration Guide and UPGRADE.md contain details on the version upgrade.

v9.0.0 is the first stable release of the v9 line. The Management API client is now generated from Auth0's OpenAPI specification via Fern, with strongly-typed requests and responses, built-in pagination, and automatic token management through the ManagementClient wrapper.

⚠️ Breaking Changes

Management API

• Minimum PHP raised from 8.1 to 8.2
• Management API client namespace changed and initialization reworked (new Management(token: ...) with sub-clients as public properties)
• Auth0::management() removed, use the ManagementClient wrapper instead
• getAll() renamed to list() across every endpoint, and sub-resource operations moved to dedicated sub-clients
• grants() renamed to userGrants, and usersByEmail() merged into users->listUsersByEmail()
• Management methods now return typed objects instead of raw PSR-7 responses

Authentication API

• client_id, response_type, and response_mode can no longer be overridden through the $params argument on Auth0::login(), Auth0::signup(), Auth0::handleInvitation(), Authentication::getLoginLink(), and the Pushed Authorization Request flow. They are always resolved from your SdkConfiguration. If you previously passed any of these through $params they are now ignored in favor of the configured value
• Auth0::handleBackchannelLogout() now stores cache entries with the configured relative expiry (backchannelLogoutExpires, default 30 days) instead of an absolute timestamp. If you ran a persistent backchannel logout cache on 8.10.0 or later, flush it once after upgrading to clear the old long-lived entries

Added

• Custom Token Exchange support via Authentication::customTokenExchange() and Auth0::loginWithCustomTokenExchange(), exchanging an external or legacy token for Auth0 tokens without a browser redirect

Changes

Added

• feat: add Agents, Organization Clients, and Directory Provisioning sync groups, plus Event Stream deliveries fix #848 (fern-api[bot])

Fixed

• fix: correct backchannel logout cache expiry to use relative duration #847 (kishore7snehil)
• fix: prevent caller params from overriding security-critical authorization parameters #845 (kishore7snehil)

Full Changelog

Added

• feat: add Agents, Organization Clients, and Directory Provisioning sync groups, plus Event Stream deliveries fix #848 (fern-api[bot])

Fixed

• fix: correct backchannel logout cache expiry to use relative duration #847 (kishore7snehil)
• fix: prevent caller params from overriding security-critical authorization parameters #845 (kishore7snehil)

Changes

Added

• feat: add XAA Resource App config, ID-JAG, branding theme identifiers, and session actor metadata

Full Changelog

Added

• feat: add XAA Resource App config, ID-JAG, branding theme identifiers, and session actor metadata #843 (fern-api[bot])

Changes

Added

• feat: add Organization Roles, Connection lifecycle events, and Token Vault access grants; rename Connection attribute identifier #838
• feat: add Network ACL curated-list match and Confirmation prompt partial #840

Fixed

• fix: regenerate session ID on login and logout to prevent session fixation #837

Breaking Changes

• feat!: remove Token Vault v1 federated connections access tokens #841
• Rename ConnectionAttributeIdentifier to EmailAttributeIdentifier #838
• Replace the None case on PhoneProviderProtectionBackoffStrategyEnum with Default #838

Full Changelog

Added

• feat: add Organization Roles, Connection lifecycle events, and Token Vault access grants, and rename Connection attribute identifier #838 (fern-api[bot])
• feat: add Network ACL curated-list match and Confirmation prompt partial #840 (fern-api[bot])

Fixed

• fix: regenerate session ID on login and logout to prevent session fixation #837 (kishore7snehil)

Breaking Changes

• feat!: remove Token Vault v1 federated connections access tokens #841 (fern-api[bot])
• Rename ConnectionAttributeIdentifier to EmailAttributeIdentifier #838 (fern-api[bot])
• Replace the None case on PhoneProviderProtectionBackoffStrategyEnum with Default #838 (fern-api[bot])

Changes

Added

• feat: add Phone Provider Protection endpoints, Token Vault privileged access, and Cross-App Access connection support

Fixed

• fix: correct offset pagination page-skipping; split Client update FedCM/native-social types

Full Changelog

Added

• feat: add Phone Provider Protection endpoints, Token Vault privileged access, and Cross-App Access connection support #835 (fern-api[bot])

Fixed

• fix: correct offset pagination page-skipping, and split Client update FedCM/native-social types #833 (fern-api[bot])

Changes

Added

• feat: add Tenant Security Headers and Connection Session Expiry; remove Branding Phone Display #830

Full Changelog

Added

• feat: add Tenant Security Headers and Connection Session Expiry, and remove Branding Phone Display #830 (fern-api[bot])

Changes

Added

• feat: add Rate Limit Policies, Events SSE, Token Vault Orgs, and HRI Client Settings #820
• feat: add SCIM Groups RBAC, User Effective Permissions/Roles, and Tenant Country Codes #826

Full Changelog

Added

• feat: add Rate Limit Policies, Events SSE, Token Vault Orgs, and HRI Client Settings #820 (fern-api[bot])
• feat: add SCIM Groups RBAC, User Effective Permissions/Roles, and Tenant Country Codes #826 (fern-api[bot])

⚠️ This is a beta release. It introduces breaking changes to the Management API. The Authentication API is unchanged. Please consult the v9 Migration Guide for detailed upgrade instructions.

🚀 What's New

This release marks a major milestone for the Auth0 PHP SDK: the Management API client has been completely rewritten using the Fern code generation tool, built directly from the Auth0 OpenAPI specification. This delivers complete, always-up-to-date API coverage with full type safety.

✨ Highlights

• 🏗️ Auto-generated Management API - Rebuilt from the Auth0 OpenAPI spec using Fern, ensuring complete endpoint coverage and consistency with the API
• 🔒 Strongly-typed requests & responses - No more associative arrays or manual JSON decoding. Every request parameter and response field is a typed PHP object with IDE autocompletion
• 📄 Built-in pagination - Pager<T> implements IteratorAggregate, automatically fetching pages as you iterate with foreach
• 🔑 Automatic token management - New ManagementClient wrapper handles OAuth 2.0 client credentials grant, token caching (PSR-6), and custom token providers out of the box
• ⚡ Built-in retry middleware - Automatic retries for rate-limited (429) responses
• 🛡️ Exception-driven error handling - Non-2xx responses throw Auth0ApiException with status code and response body, replacing manual status code checks

🔄 What's Changed

The Authentication API is completely unchanged. Auth0\SDK\Auth0, session handling, token verification, and all authentication flows work exactly as before.

The Management API has breaking changes:

📦 Installation

composer require auth0/auth0-php:9.0.0-beta.0

Running composer require auth0/auth0-php without a version constraint will install the latest stable v8 release.

🔧 Quick Start

use Auth0\SDK\API\Management\Wrapper\ManagementClient;
use Auth0\SDK\API\Management\Wrapper\ManagementClientOptions;
use Auth0\SDK\API\Management\Users\Requests\ListUsersRequestParameters;

$client = new ManagementClient(new ManagementClientOptions(
    domain: 'tenant.auth0.com',
    clientId: 'CLIENT_ID',
    clientSecret: 'CLIENT_SECRET',
));

// List users with automatic pagination
$pager = $client->users->list(new ListUsersRequestParameters([
    'perPage' => 50,
    'includeTotals' => true,
]));

foreach ($pager as $user) {
    echo $user->getEmail();
}

📚 Resources

• v9 Migration Guide (v8 -> v9)
• Examples
• API Reference

⚠️ Breaking Changes

• Management API methods return typed objects instead of ResponseInterface
• Management API methods accept typed request classes instead of arrays
• Sub-clients accessed as properties (->users) instead of methods (->users())
• getAll() renamed to list() across all endpoints
• HttpResponsePaginator replaced by Pager<T>
• Non-2xx responses throw Auth0ApiException automatically
• Minimum PHP version remains 8.2 (unchanged from v8.19.0)

🙏 Feedback

This is a beta release - we would love your feedback! Please open an issue if you encounter any problems or have suggestions.

Full Changelog

Breaking Changes

• Management API client has been completely rewritten using Fern code generation from the Auth0 OpenAPI specification
• Management API methods now return strongly-typed response objects instead of PSR-7 ResponseInterface
• Management API methods now accept typed request parameter classes instead of associative arrays
• Management sub-clients are accessed as properties (->users) instead of methods (->users())
• List methods renamed from getAll() to list()
• Pagination now uses built-in Pager<T> instead of HttpResponsePaginator
• Non-2xx API responses now throw Auth0ApiException instead of returning error responses

Added

• New ManagementClient wrapper with built-in OAuth 2.0 client credentials token management
• Support for static tokens, automatic client credentials grant, PSR-6 token caching, and custom token providers
• Strongly-typed request and response objects for all Management API endpoints
• Built-in Pager<T> pagination with automatic page fetching
• Built-in retry middleware for rate-limited requests
• Telemetry headers (Auth0-Client, User-Agent) on Management API requests
• Complete API coverage auto-generated from the Auth0 OpenAPI specification
• UPGRADE.md v8 to v9 migration guide

Unchanged

• Authentication API (Auth0\SDK\API\Authentication) - no changes
• Session handling, token management, and the Auth0\SDK\Auth0 entry point class - no changes

Fixed

• Security fix: Resolve CVE-2026-34236

Changed

• Dropped support for PHP 8.1 (EOL since Dec 2025). The minimum supported PHP version is now 8.2.

Full Changelog

Fixed

• Security fix: Resolve CVE-2026-34236

Changed

• Dropped support for PHP 8.1 (EOL since Dec 2025). The minimum supported PHP version is now 8.2.

Full Changelog

Fixed

• Security fix: Resolve CVE-2025-68129

Full Changelog

Fixed

• Security fix: Resolve CVE-2025-58769

Full Changelog

Added

• feat: add Network ACLs management API support #797 (kishore7snehil)

Fixed

• chore: Bump deps, remove Semgrep workflow, doc update #798 (kishore7snehil)

Full Changelog

Added

• feat: Adding M2M Quota Support #788 (kishore7snehil)

Full Changelog

Fixed

• Security fix: Resolve CVE-2025-47275

Full Changelog

Added

• feat: Adding Support For BYOK #782 (kishore7snehil)

• feat: Validation Test Case For Show as Button Parameter #783 (kishore7snehil)

Fixed

• docs: Adjusted link typo on codeExchange method to the right url #782 (GabrielBrittoDev)

Full Changelog

Added

• feat: Adding client credentials support #775 (kishore7snehil)

• feat: Adding Support For CYOK #779 (kishore7snehil)

Fixed

• fix: fix jobs test fail #773 (yasuaki640)

Full Changelog

Fixed

• fix: Resolve erroneous exception throw on tenant domain validation #755 (ramonschriks)

Full Changelog

Added

• feat: Support validating tokens with tenant domain in the case of custom domains #753 (ramonschriks)

Full Changelog

Added

• feat(SDK-4731): Implement support for Back-Channel Logout #747 (evansims)

Changed

• PHP 8.1 is now the minimum supported runtime #748 (evansims)

Full Changelog

Fixed

• fix: Remove redundant token verification step #742 (evansims)

Full Changelog

Fixed

• fix(SDK-4716): Resolve thrown exception when enumerating device cookies that include non-string keys/names #739 (evansims)

Full Changelog

Added

• feat(SDK-4543): Support Organizations with Client Grants #736 (evansims)

Added

• Support initiate_login_uri property for PATCH requests to the /api/v2/clients/:id Management API endpoint. #732

Fixed

• Token generator typo in claim header. #729

Changed

• composer.json now identifies mbstring as a required extension. #730
• PHP 8.3 nightlies have been added to the continuous integration testing matrix. #733

Fixed

• Corrected Management API route for deploy action endpoint by @speercy (#723)

Added

• Organization Name support added for Authentication API and token handling¹ (#719)

Note ¹ To use this feature, an Auth0 tenant must have support for it enabled. This feature is not yet available to all tenants.

Added

• PAR (Pushed Authorization Request) support¹ (#714):
  • Auth0\SDK\API\Authentication\PushedAuthorizationRequest is a new class for issuing Pushed Authorization Requests and producing authorization links for them.
  • Auth0\SDK\API\Authentication::pushedAuthorizationRequest() has been added as a shortcut method for returning a configured instantiation of the above class.
  • Auth0\SDK\Auth0::login() has been updated to support issuing Pushed Authorization Requests and returning authorization links for them.
  • Auth0\SDK\Configuration\SdkConfiguration has been updated to accept a pushedAuthorizationRequest boolean to enable this feature.
• Auth0\SDK\Auth0::isAuthenticated() has been added as a shortcut method. It is an alias for getCredentials() !== null.

Note ¹ To use this feature, an Auth0 tenant must have support for it enabled. This feature is not yet available to all tenants.

This release improves the SDK's automatic discovery process of compatible HTTP clients, factories and messages (PSR-18, 17 and 7, respectively). If you encounter issues with your implementation not being discovered, please open an issue.

This release also introduces support for a number of additional Management API endpoints.

Added

• State Management

  • Added Auth0\SDK\Auth0::refreshState() to force a refresh of the SDK's internal state. This is useful when you have updated the SDK's configuration and want to ensure the SDK is using the latest values.

• Management API

  • Auth0\APIs\Management\Users
    • DELETE /users/:id/authenticators → deleteAllAuthenticators() (#702) (Documentation)
  • Support for Authentication Method endpoints: (#707):
    • GET /api/v2/users/:user/authentication-methods → getAuthenticationMethods() (Documentation)
    • PUT /api/v2/users/:user/authentication-methods → replaceAuthenticationMethods() (Documentation)
    • DELETE /api/v2/users/:user/authentication-methods → deleteAuthenticationMethods(string user) (Documentation)
    • POST /api/v2/users/:user/authentication-methods → createAuthenticationMethod() (Documentation)
    • GET /api/v2/users/:user/authentication-methods/:method → getAuthenticationMethod() (Documentation)
    • PATCH /api/v2/users/:user/authentication-methods/:method → updateAuthenticationMethod() (Documentation)
    • DELETE /api/v2/users/:user/authentication-methods/:method → deleteAuthenticationMethod() (Documentation)

Fixed

• Transient storage would sometimes not be fully cleared after a successful code exchange under certain conditions.
• Calls to certain methods under Auth0\SDK\API\Authentication with manually assigned client_id or client_secret parameters could have those values overwritten by the SDK's assigned configuration. #705

Changed

• Upgraded test suite to PEST 2.0 framework.
• Updated code styling rules, along with some light refactoring.
• Updated production dependencies:
  • Replaced php-http/discovery dependency with psr-discovery/all.
  • Replaced php-http/httplug dependency with psr-discovery/all.
• Updated development dependencies:
  • Removed ergebnis/composer-normalize as it now runs in CI.
  • Removed firebase/php-jwt as it was replaced by an in-library generator.
  • Replaced hyperf/event with symfony/event-dispatcher.
  • Replaced laravel/pint with friendsofphp/php-cs-fixer.
  • Replaced nyholm/psr7 with psr-mock/http-factory-implementation.
  • Replaced php-http/mock-client with psr-mock/http-client-implementation.
  • Updated vimeo/psalm to 5.8.
  • Updated phpstan/phpstan to 1.10.
  • Updated rector/rector to 0.15.

Thanks to our contributors for this release: knash94

Added

• Client Assertion (private_key_jwt) support #699 (evansims)
• Client Credentials management endpoints #700 (evansims)
• JSON Web Token generator classes, Auth0\SDK\Token\Generator and Auth0\SDK\Token\ClientAssertionGenerator. #698 (evansims)

Changed

• Restore test coverage to 100% #697 (evansims)
• Exclude unnecessary files from distribution package #696 (ramsey)

Fixed

• fix: Always store provided state in transient medium #674 (evansims)

Fixed

• fix: emailPasswordlessStart() incorrectly passes params as array under some conditions #670 (evansims)
• fix: Remove redundant Cache getItem() call in Auth0\SDK\Token\Verifier::getKeySet() #669 (pkivits-litebit)

Fixed

• fix: Restore previous behavior of SdkConfiguration::setScope() being nullable #665 (evansims)

Fixed

• [SDK-3722] Fix: Stateless strategies should not invoke stateful session classes #662 (evansims)

Fixed

• Fix SdkConfiguration::setScope() not assigning default values when an empty array is passed #659 (evansims)

Fixed

• Configuration validator improvements #657 (evansims)

Fixed

• [SDK-3719] Fix PHP 8.0+ SdkConfiguration named arguments usage #654 (evansims)

Changed

• [SDK-3647] Add PHP 8.2.0-dev to test matrix #650 (evansims)

Fixed

• [SDK-3646] Reliability and performance improvements to CookieStore #649 (evansims)

Added

• [SDK-3636] Add PSR-14 Event Dispatcher, for ultra customizable session storage purposes #646 (evansims)

Changed

• [SDK-3633] Treat passing an empty string to SdkConfiguration as the default undefined value type of NULL #643 (evansims)
• [SDK-3635] Enable configuration of SessionStore and CookieStore samesite property #645 (evansims)
• [SDK-3634] Add hardcoded debugging flag to CookieStore to disable encryption of session cookies #644 (evansims)
• [SDK-3632] Update getRequestParameter() filter to use FILTER_SANITIZE_FULL_SPECIAL_CHARS and allow passing extra filter options #642 (evansims)
• [SDK-3631] Defer/batch "Set-Cookie" headers at login() for transient cookies, and clear() #641 (evansims)

Fixed

• Fixed an issue in Auth0\SDK\Configuration\SdkConfiguration where customDomain was not properly formatted in some configurations, leading to inconsistencies in certain SDK functions, such as Token validation. customDomain is now formatted identically to domain. #633 (evansims)

Closed Issues

• Resolves #630 (barasimumatik)

Many thanks to our community contributors for this release: elbebass, fullstackfool, jeromefitzpatrick, marko-ilic and sepiariver.

Added

• Add bearer token extraction helper, Auth0\SDK\Auth0::getBearerToken() #620 (evansims)
• Add configuration strategy constants, e.g. Auth0\SDK\Configuration\SdkConfiguration::STRATEGY_API #619 (evansims)

Changed

• Throw Auth0\SDK\Exception\InvalidTokenException on JsonException #614 (marko-ilic)
• Throw Auth0\SDK\Exception\NetworkException when Management API credential exchange fails #608 (sepiariver)

Documentation Contributions

• Correct the new method name for get_authorize_link() for 8.x in UPGRADE.md #623 (jeromefitzpatrick)
• Remove PHP 7.3 README note (deprecated) #610 (evansims)
• Update CONTRIBUTING.md guidance #609 (sepiariver)
• Update README.md guidance on management configuration strategy (domain is required) #604 (fullstackfool)
• Correct README.md typos in Management API example #602 (elbebass)

Other Improvements

• Relax pestphp/pest-plugin-parallel dev dependency from ^0.2 to ^0.2 || ^1.0 #617
• Bump firebase/php-jwt dev dependency to ^6.0 #613 (evansims)
• Add Semgrep to continous integration test suite #616 (evansims)

Added

• Add Attack Protection endpoints #593 (evansims)

Fixed

• Auth0->renew(): now correctly updates all appropriate session details after a successful token refresh #593 (evansims)

Fixed

• Auth0->exchange(): optimize setcookie() calls #591 (Nebual)

Fixed

• Require domain configuration for management strategy #589 (evansims)

Documentation

• Update UPGRADE.md with additional notes about Auth0::login() changes from v7. #585 (BGehrels)
• Update UPGRADE.md with additional notes about Auth0::exchange() changes from v7. #584 (BGehrels)

Tests

• Add Semgrep to test suite #588 (evansims)
• Upgrade test suite to use 8.1 GA (up from RC builds) #587 (evansims)
• Fix warnings introduced in new Psalm update #586 (evansims)

Changes

• Introduce Interfaces to Final Classes #581 (komando82)

Fixed

• Resolve SessionStore::purge() not iterating over session storage when a falsey value is stored #577 (evansims)

Fixed

• Simplify decoding of Access Tokens via Auth0::decode() #534 (shadowhand)

BEFORE YOU UPGRADE

• This is a major release that includes breaking changes. Please see UPGRADE.md before upgrading. This release will require changes to your application.
• The SDK no longer specifically relies on Guzzle for network requests. Options for supplying your libraries of choice have been added through PSR-18 and PSR-17 configuration options.
• PHP 7.4 is now the minimum supported PHP version, but we encourage using PHP 8.0. PHP 7.4 will be the last supported 7.x release. This library follows the official support schedule for PHP.

8.0 Highlights

• Updated SDK API for more intuitive use and improved usability. Now follows fluent interface principles.
• Updated SDK API designed with PHP 8.0's named arguments as the encouraged interface method.
• New configuration object, SdkConfiguration, allows for dynamic changes within your application.
• Updated PHP language support, including typed properties and return types, are now used throughout the SDK.
• Added support for the following PHP-FIG standards interfaces:
  • PSR-6 caches are now used for caching JWKs and Management API tokens.
  • PSR-7 HTTP messages are now returned by methods that initiate network requests.
  • PSR-14 events are now raised, allowing for deeper integration into the SDK's behavior.
  • PSR-17 HTTP factories are now used during network requests for generating PSR-7 messages.
  • PSR-18 HTTP clients are now supported, allowing you to choose your network client.
• Improved Token handling system.
• Encrypted session cookies, with cookies being the default session handler. PHP sessions may be phased out in a future release.
• New Management API auto-pagination helper for iterating through API results.
• PKCE is now enabled by default.

For a complete overview of API changes, please see UPGRADE.md.

For guidance on using the new configuration interface or SDK API, please see README.md.

Changelog entries for releases prior to 8.0 have been relocated to CHANGELOG.ARCHIVE.md.