From 1e44613dc017468608983dfc1363804d02ed8fc4 Mon Sep 17 00:00:00 2001 From: Sourav Basu Date: Wed, 15 Jul 2026 17:55:58 +0530 Subject: [PATCH 1/2] Added migration guide for v5 to v6 --- UPGRADING.md | 221 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 221 insertions(+) create mode 100644 UPGRADING.md diff --git a/UPGRADING.md b/UPGRADING.md new file mode 100644 index 00000000..5cbb62b5 --- /dev/null +++ b/UPGRADING.md @@ -0,0 +1,221 @@ +# v6 Migration Guide + +A guide to migrating the Auth0 Python SDK from v5 to v6. + +- [Overall changes](#overall-changes) +- [Breaking changes](#breaking-changes) + - [Federated connections tokensets removed](#federated-connections-tokensets-removed) + - [`federated_connections_access_tokens` field removed](#federated_connections_access_tokens-field-removed) + - [`read:federated_connections_tokens` / `delete:federated_connections_tokens` scopes removed](#readfederated_connections_tokens--deletefederated_connections_tokens-scopes-removed) + - [`ClientSessionTransferDelegationDeviceBindingEnum` narrowed](#clientsessiontransferdelegationdevicebindingenum-narrowed) + - [`ConnectionAttributeIdentifier` split into three types](#connectionattributeidentifier-split-into-three-types) + - [`PhoneProviderProtectionBackoffStrategyEnum` value renamed](#phoneproviderprotectionbackoffstrategyenum-value-renamed) + - [`ListRolesOffsetPaginatedResponseContent` pagination fields now required](#listrolesoffsetpaginatedresponsecontent-pagination-fields-now-required) +- [New features](#new-features) + - [Network ACL: `auth0_managed` field](#network-acl-auth0_managed-field) + - [Organizations: role members endpoint](#organizations-role-members-endpoint) + - [Organizations: third-party client access](#organizations-third-party-client-access) + - [Other additions](#other-additions) + +## Overall changes + +v6 removes one deprecated Management API surface (federated connections +tokensets) and tightens a handful of generated types to match the current +Auth0 Management API contract. Most applications will only be affected if +they use the specific types or endpoints listed below. + +The Authentication API is not affected by this release. + +## Breaking changes + +### Federated connections tokensets removed + +The `users.federated_connections_tokensets` sub-client and its `list`/`delete` +methods have been removed, along with the `FederatedConnectionTokenSet` and +`ConnectionFederatedConnectionsAccessTokens` types. This endpoint is no longer +part of the Auth0 Management API. + +```python +# v5 +client.users.federated_connections_tokensets.list(id="user_id") +client.users.federated_connections_tokensets.delete(id="user_id", tokenset_id="tokenset_id") +``` + +```python +# v6 +# No replacement — the endpoint has been removed from the Management API. +``` + +If you depend on this functionality, do not upgrade until you have confirmed +an alternative with Auth0 support. + +### `federated_connections_access_tokens` field removed + +The optional `federated_connections_access_tokens` field has been removed +from: + +- `ConnectionOptionsAzureAd` +- `ConnectionOptionsCommonOidc` +- `ConnectionOptionsGoogleApps` +- `ConnectionPropertiesOptions` +- `UpdateConnectionOptions` + +Any code reading or setting this field on the above types will need to +remove that usage; passing it will simply be dropped as an unrecognized +field. + +### `read:federated_connections_tokens` / `delete:federated_connections_tokens` scopes removed + +These two values are no longer valid members of `OauthScope`. Remove any +references to them when requesting or checking scopes. + +### `ClientSessionTransferDelegationDeviceBindingEnum` narrowed + +The `"asn"` literal value has been removed. The enum now only accepts `"ip"`: + +```python +# v5 +ClientSessionTransferDelegationDeviceBindingEnum = typing.Union[typing.Literal["ip", "asn"], typing.Any] +``` + +```python +# v6 +ClientSessionTransferDelegationDeviceBindingEnum = typing.Union[typing.Literal["ip"], typing.Any] +``` + +If you were setting this value to `"asn"`, update it to `"ip"` — this matches +the current Management API's accepted values. + +### `ConnectionAttributeIdentifier` split into three types + +`ConnectionAttributeIdentifier` has been removed with no compatibility alias. +It is replaced by three narrower types, one per attribute: + +| Attribute field | v5 type | v6 type | Shape | +| --- | --- | --- | --- | +| `EmailAttribute.identifier` | `ConnectionAttributeIdentifier` | `EmailAttributeIdentifier` | `{active?, default_method?: DefaultMethodEmailIdentifierEnum}` | +| `PhoneAttribute.identifier` | `ConnectionAttributeIdentifier` | `PhoneAttributeIdentifier` | `{active?, default_method?: DefaultMethodPhoneNumberIdentifierEnum}` | +| `UsernameAttribute.identifier` | `ConnectionAttributeIdentifier` | `UsernameAttributeIdentifier` | `{active?}` (no `default_method`) | + +```python +# v5 +from auth0.management.types import ConnectionAttributeIdentifier + +identifier = ConnectionAttributeIdentifier(active=True, default_method="email") +``` + +```python +# v6 +from auth0.management.types import EmailAttributeIdentifier + +identifier = EmailAttributeIdentifier(active=True, default_method="email") +``` + +`EmailAttributeIdentifier` has the same shape as the old +`ConnectionAttributeIdentifier` and is a drop-in replacement for code that +was only ever used with `EmailAttribute`. Code using +`ConnectionAttributeIdentifier` with `PhoneAttribute` or `UsernameAttribute` +must switch to `PhoneAttributeIdentifier` or `UsernameAttributeIdentifier` +respectively; `UsernameAttributeIdentifier` does not support +`default_method`. + +### `PhoneProviderProtectionBackoffStrategyEnum` value renamed + +The `"none"` literal has been replaced with `"default"`: + +```python +# v5 +PhoneProviderProtectionBackoffStrategyEnum = typing.Union[typing.Literal["exponential", "none"], typing.Any] +``` + +```python +# v6 +PhoneProviderProtectionBackoffStrategyEnum = typing.Union[typing.Literal["exponential", "default"], typing.Any] +``` + +Replace any use of `"none"` with `"default"`. + +### `ListRolesOffsetPaginatedResponseContent` pagination fields now required + +`start`, `limit`, and `total` are no longer optional: + +```python +# v5 +start: typing.Optional[float] = None +limit: typing.Optional[float] = None +total: typing.Optional[float] = None +``` + +```python +# v6 +start: float +limit: float +total: float +``` + +Deserializing a role-list response that is missing any of these fields now +raises `pydantic.ValidationError` instead of silently defaulting to `None`. +This matches the Management API, which always returns these fields for this +endpoint. + +## New features + +### Network ACL: `auth0_managed` field + +`NetworkAclMatch` gains an optional `auth0_managed: Optional[List[str]]` +field (serialized as `auth0_managed`), available on both the `match` and +`not_match` rule blocks. Use it to reference Auth0-managed lists when +matching or excluding traffic: + +```python +from auth0.management.types import NetworkAclMatch + +match = NetworkAclMatch(auth_0_managed=["tor-exit-nodes"]) +``` + +The Python attribute is `auth_0_managed`; it serializes to `auth0_managed` +over the wire. Both spellings are accepted as the constructor keyword. + +### Organizations: role members endpoint + +New sub-clients `organizations.roles` and `organizations.roles.members` +expose `GET /api/v2/organizations/{id}/roles/{role_id}/members`: + +```python +for member in client.organizations.roles.members.list(id="org_id", role_id="role_id"): + print(member) +``` + +This returns a `SyncPager`/`AsyncPager` of `RoleMember`, wrapping +`ListOrganizationRoleMembersResponseContent`. + +### Organizations: third-party client access + +`create()`/`update()` and all organization response types gain +`third_party_client_access: Optional[OrganizationThirdPartyClientAccessEnum]` +(`Literal["block", "allow"]`), controlling whether third-party clients can +access the organization. + +### Other additions + +- **Grants**: `UserGrant.organization_id: Optional[str]` (read-only), returned + from `GET /grants`. +- **Connections**: `discovery_url` / `oidc_metadata` are now available on + `samlp` connections (previously OIDC-only), via new `ConnectionsDiscoveryUrl` + / `ConnectionsOidcMetadata` on `ConnectionPropertiesOptions` and + `UpdateConnectionOptions`. +- **Event Streams**: new event-type values `connection.created`, + `connection.deleted`, `connection.updated` on `EventStreamEventTypeEnum`, + `EventStreamDeliveryEventTypeEnum`, `EventStreamSubscribeEventsEventTypeEnum`, + and `EventStreamTestEventTypeEnum`; new + `EventStreamCloudEventConnection{Created,Deleted,Updated}*` payload types; + and `EventStreamSubscribeEventsResponseContent` extended with the + connection event variants. +- **Token Vault**: new `grants: Optional[List[TokenVaultPrivilegedAccessGrant]]` + on the privileged-access credential/public-key types. + `TokenVaultPrivilegedAccessGrant`: `{connection: str, scopes: List[str]}`. +- **Errors**: new error body types `NotFoundErrorBody`/`NotFoundErrorBodyError` + and `TooManyRequestsErrorBody`/`TooManyRequestsErrorBodyError`. +- **CloudEvent**: `specversion` is now typed as + `EventStreamCloudEventSpecVersionEnum` (`Literal["1.0"]` + `Any` fallback) + instead of `str`, across group/org/user CloudEvent types. From 30b1089ae90f33c4b431b9d868edd89a6d4697ce Mon Sep 17 00:00:00 2001 From: Sourav Basu Date: Wed, 15 Jul 2026 18:12:35 +0530 Subject: [PATCH 2/2] Updated UPGRADING.md doc --- UPGRADING.md | 78 +++++----------------------------------------------- 1 file changed, 7 insertions(+), 71 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index 5cbb62b5..ed653dbf 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -11,11 +11,6 @@ A guide to migrating the Auth0 Python SDK from v5 to v6. - [`ConnectionAttributeIdentifier` split into three types](#connectionattributeidentifier-split-into-three-types) - [`PhoneProviderProtectionBackoffStrategyEnum` value renamed](#phoneproviderprotectionbackoffstrategyenum-value-renamed) - [`ListRolesOffsetPaginatedResponseContent` pagination fields now required](#listrolesoffsetpaginatedresponsecontent-pagination-fields-now-required) -- [New features](#new-features) - - [Network ACL: `auth0_managed` field](#network-acl-auth0_managed-field) - - [Organizations: role members endpoint](#organizations-role-members-endpoint) - - [Organizations: third-party client access](#organizations-third-party-client-access) - - [Other additions](#other-additions) ## Overall changes @@ -61,8 +56,11 @@ from: - `UpdateConnectionOptions` Any code reading or setting this field on the above types will need to -remove that usage; passing it will simply be dropped as an unrecognized -field. +remove that usage. Note that these models are configured with +`extra="allow"`, so passing `federated_connections_access_tokens` is **not** +silently dropped — it is retained on the model and still serialized into the +outbound request. Remove the field explicitly rather than relying on the SDK +to strip it. ### `read:federated_connections_tokens` / `delete:federated_connections_tokens` scopes removed @@ -101,14 +99,14 @@ It is replaced by three narrower types, one per attribute: # v5 from auth0.management.types import ConnectionAttributeIdentifier -identifier = ConnectionAttributeIdentifier(active=True, default_method="email") +identifier = ConnectionAttributeIdentifier(active=True, default_method="email_otp") ``` ```python # v6 from auth0.management.types import EmailAttributeIdentifier -identifier = EmailAttributeIdentifier(active=True, default_method="email") +identifier = EmailAttributeIdentifier(active=True, default_method="email_otp") ``` `EmailAttributeIdentifier` has the same shape as the old @@ -157,65 +155,3 @@ Deserializing a role-list response that is missing any of these fields now raises `pydantic.ValidationError` instead of silently defaulting to `None`. This matches the Management API, which always returns these fields for this endpoint. - -## New features - -### Network ACL: `auth0_managed` field - -`NetworkAclMatch` gains an optional `auth0_managed: Optional[List[str]]` -field (serialized as `auth0_managed`), available on both the `match` and -`not_match` rule blocks. Use it to reference Auth0-managed lists when -matching or excluding traffic: - -```python -from auth0.management.types import NetworkAclMatch - -match = NetworkAclMatch(auth_0_managed=["tor-exit-nodes"]) -``` - -The Python attribute is `auth_0_managed`; it serializes to `auth0_managed` -over the wire. Both spellings are accepted as the constructor keyword. - -### Organizations: role members endpoint - -New sub-clients `organizations.roles` and `organizations.roles.members` -expose `GET /api/v2/organizations/{id}/roles/{role_id}/members`: - -```python -for member in client.organizations.roles.members.list(id="org_id", role_id="role_id"): - print(member) -``` - -This returns a `SyncPager`/`AsyncPager` of `RoleMember`, wrapping -`ListOrganizationRoleMembersResponseContent`. - -### Organizations: third-party client access - -`create()`/`update()` and all organization response types gain -`third_party_client_access: Optional[OrganizationThirdPartyClientAccessEnum]` -(`Literal["block", "allow"]`), controlling whether third-party clients can -access the organization. - -### Other additions - -- **Grants**: `UserGrant.organization_id: Optional[str]` (read-only), returned - from `GET /grants`. -- **Connections**: `discovery_url` / `oidc_metadata` are now available on - `samlp` connections (previously OIDC-only), via new `ConnectionsDiscoveryUrl` - / `ConnectionsOidcMetadata` on `ConnectionPropertiesOptions` and - `UpdateConnectionOptions`. -- **Event Streams**: new event-type values `connection.created`, - `connection.deleted`, `connection.updated` on `EventStreamEventTypeEnum`, - `EventStreamDeliveryEventTypeEnum`, `EventStreamSubscribeEventsEventTypeEnum`, - and `EventStreamTestEventTypeEnum`; new - `EventStreamCloudEventConnection{Created,Deleted,Updated}*` payload types; - and `EventStreamSubscribeEventsResponseContent` extended with the - connection event variants. -- **Token Vault**: new `grants: Optional[List[TokenVaultPrivilegedAccessGrant]]` - on the privileged-access credential/public-key types. - `TokenVaultPrivilegedAccessGrant`: `{connection: str, scopes: List[str]}`. -- **Errors**: new error body types `NotFoundErrorBody`/`NotFoundErrorBodyError` - and `TooManyRequestsErrorBody`/`TooManyRequestsErrorBodyError`. -- **CloudEvent**: `specversion` is now typed as - `EventStreamCloudEventSpecVersionEnum` (`Literal["1.0"]` + `Any` fallback) - instead of `str`, across group/org/user CloudEvent types.