4.0.0 (2025-07-31)

Highlights

API v2: The New Resource-Based Standard

With this release, we've completed the migration of core resources – including instances, organizations, projects, applications and users – to our powerful new resource-based API. This modernization provides a more consistent, efficient, and scalable foundation for interacting with ZITADEL.

• Full API Documentation: https://zitadel.com/docs/apis/v2
• Seamless Transition with our Migration Guide: https://zitadel.com/docs/apis/migration_v1_to_v2

Below is an overview of V2 APIs, categorized in Beta and General Availability (GA) as well as a complete list of endpoints that are deprecated:

General Availability (GA)

• Actions V2
• Caches V2

Beta

• Instance Service V2
• Project V2
• App V2
• Authorization V2
• Permission V2
• Settings V3

Deprecated Endpoints

Organization Objects V1 Users V1 - GetOrgByDomainGlobal - AddMachineUser - UpdateMachine - GenerateMachineSecret - RemoveMachineSecret - GetMachineKeyByIDs - ListMachineKeys - AddMachineKey - RemoveMachineKey - UpdateUserName - SetUserMetadata - BulkSetUserMetadata - ListUserMetadata - GetUserMetadata - RemoveUserMetadata - BulkRemoveUserMetadata - UpdateHumanPhone - GetPersonalAccessTokenByIDs - ListPersonalAccessTokens - AddPersonalAccessToken - RemovePersonalAccessToken - ListAppKeys

Projects V1 - GetProjectByID - GetGrantedProjectByID - ListProjects - ListGrantedProjects - ListGrantedProjectRoles - AddProject - UpdateProject - DeactivateProject - ReactivateProject - RemoveProject - ListProjectRoles - AddProjectRole - BulkAddProjectRoles - UpdateProjectRole - RemoveProjectRole - GetProjectGrantByID - ListProjectGrants - ListAllProjectGrants - AddProjectGrant - UpdateProjectGrant - DeactivateProjectGrant - ReactivateProjectGrant - RemoveProjectGrant

Members V1 - ListUserMemberships - ListOrgMembers - AddOrgMember - UpdateOrgMember - RemoveOrgMember - ListProjectMembers - AddProjectMember - UpdateProjectMember - RemoveProjectMember - ListProjectGrantMembers - AddProjectGrantMember - UpdateProjectGrantMember - RemoveProjectGrantMember

Instance Lifecycle V1 System Service V1 - GetMyInstance - ListInstanceDomains - ListInstanceTrustedDomains - AddInstanceTrustedDomain - RemoveInstanceTrustedDomain

Instance Objects V1 Organizations V1 - GetOrgByID - IsOrgUnique - GetDefaultOrg

Members V1 - ListIAMMembers - AddIAMMember - UpdateIAMMember - RemoveIAMMember

GRPC APIs with ConnectRPC

All new v2 APIs will exclusively leverage gRPC with ConnectRPC, discontinuing support for OpenAPI 2.0 for new endpoints. This ensures a robust, high-performance, and future-proof integration experience.

Note: Existing APIs from previous releases remain unaffected by this change.

Login V2 as default

Our re-engineered Login UI, leveraging the Session API, is now feature-complete (all features from login v1 supported) and will be the default experience for all new customers.

Service Ping

Introducing Service Ping, a new mechanism for securely sending anonymized metrics and usage data from Zitadel instances to our customer portal. This opt-out feature is crucial for understanding product usage and will serve as the foundation for exciting upcoming features, including decentralized AI model training based on aggregated data. Have a look at our documentation to see what data is sent and how to opt out: [Link to Docs]

Bug Fixes

• Actions V2 improve deleted target handling in executions (#9822) (48c1f7e)
• actions v2beta with api design for GA (#10303) (f0fa897), closes #10138
• actions: default sorting column to creation date (#9795) (74ace1a), closes #9763
• actions: handle empty deny list correctly (#9753) (4ffd4ef)
• add current state for execution handler into setup (#9863) (21167a4)
• add user id index on sessions8 (#9834) (8cb1d24)
• allow invite codes for users with verified mails (#9962) (833f627)
• allow user self deletion (#9828) (898366c), closes #9763
• api: correct mapping of user state queries (#9956) (eb0eed2)
• api: CORS for connectRPC and grpc-web (#10227) (1b01fc6)
• api: return typed saml form post data in idp intent (#10136) (64a03fb), closes [zitadel/typescript#410](https://github.com/zitadel/typescript/issues/410)
• Auto cleanup failed Setup steps if process is killed (#9736) (aa9ef8b)
• cache: prevent org cache overwrite by other instances (#10012) (15902f5)
• console: correct count for users list, show create timestamp in user details (#9705) (bb59192)
• console: list of unique v2 sessions (#9778) (ceaa737)
• console: org context for V2 user creation (#9971) (1a80e26)
• correct handling of removed targets (#9824) (a05f7ce)
• correct id filter for project service (#10035) (647b3b5)
• correct permissions for projects on v2 api (#9973) (85e3b74), closes #9972
• correct unmarshalling of IdP user when using Google (#9799) (3953879)
• correct user v2 api docs for v3 (#10112) (5da5ccd), closes #10083
• correctly "or"-join ldap userfilters (#9855) (1383cb0), closes #7003
• correctly use single matching user (by loginname) (#9865) (867e9cb)
• defaults: comment default SystemAPIUsers (#9813) (ed4e226)
• enable opentelemetry metrics for river queue (#10044) (83839fc), closes #10043
• eventstore: use decimal, correct mirror (#9914) (131f70d)
• FE: allow only enabled factors to be displayed on user page (#9313) (839c761)
• features: remove the improved performance enumer (#9819) (0465d50)
• fields: project by id and resource owner (#10034) (6c309d6)
• fix login image (#10355) (819b82e)
• idp user information mapping (#9892) (1b2fd23)
• import/export: fix for deactivated user/organization being imported as active (#9992) (77f0a10)
• Improve Actions V2 Texts and reenable in settings (#9814) (d930a09), closes #7248 #9688
• Improve Actions V2 translations (#9826) (02acc93)
• instance: add web key generation to instance defaults (#9815) (91bc71d)
• invite code generation after multiple verification failures (#10323) (fe3ccc8), closes /github.com/zitadel/zitadel/blob/main/internal/command/user_v2_invite_model.go#L69 /github.com/zitadel/zitadel/blob/main/internal/command/user_v2_invite.go#L60 #9860
• login v1: correctly auto-link users on organizations with suffixed usernames (#10205) (8f61b24)
• login v1: ensure the user's organization is always set into the token context (#10221) (2821f41)
• login v1: handle password reset when authenticating with email or phone number (#10228) (ffe6d41)
• login: better error handling for saml cookie serialization (#10259) (14a5946)
• login: changed permission check for sending invite code on log in (#10197) (23d6d24)
• login: Copy to clipboard button in MFA login step now compatible in non-chrome browser (#9880) (77b4333), closes #9379
• login: default lifetime, show expiration on accounts page (#10297) (a3e1d6a)
• login: email or phone query, session context from loginname (#10158) (47f0486)
• login: encode formpost data to cookie (#10173) (253beb4)
• login: ensure correct i18n locale context (#10156) (325aa1f)
• login: render error properly when auto creation fails (#9871) (a73acbc), closes #9766
• login: saml cookie settings (#10266) (968b08e)
• metadata decoding and encoding #9816 (#10024) (c1cda9b)
• mirror: add max auth request age configuration (#9812) (181186e)
• org: adding unique constrants to not allow an org to be added twice with same id (#10243) (870fefe)
• packages: cjs, and module resolution fix (#10322) (c46fd01)
• permission checks on session API (40094be)
• project grant permissions v2 remove (#10337) (ec12893)
• projection: remove users with factors (#9877) (d79d5e7)
• queue: reset projection list before each Register call (#10001) (b660d6a)
• remove action feature flag and include execution (#9727) (b8ba7bd), closes #9759 #9710
• remove index es_instance_position (#9862) (d71795c), closes #9837 #9837 #9863
• saml: Push AuthenticationSucceededOnApplication milestone for SAML sessions (#10263) (6d11145), closes #9592
• scim: add a metadata config to ignore random password sent during SCIM create (#10296) (8fff45d), closes #10009
• scim: add type attribute to ScimEmail (#9690) (3a4298c)
• service ping: correct endpoint, validate and randomize default interval (#10166) (82cd1ce)
• settings: fix for setting restricted languages (#9947) (b46c41e)
• setup: execute s54 (#9849) (a626678)
• setup: reenable index creation (#9868) (60ce32c)
• sorting options of the ListInstanceTrustedDomains() gRPC endpoint (#10172) (0ceec60), closes #9839
• text buttons overflow in login page (#9637) (257bef9), closes #7619
• typoe in "Migrate from ZITADEL" documentation (#9867) (056b01f)
• update link to postgres-insecure example in docs (#9802) (205beb6)
• update session recordings for posthog (#9775) (ce823c9)
• Use ID ordering for the executions in Actions v2 (#9820) (002c3eb), closes #9688
• validate proto header and provide https enforcement (#9975) (c097887)

• webauthn: allow to use "old" passkeys/u2f credentials on session API (#10150) (71575e8)

• BREAKING CHANGE: release candidate v4 (8f0b7eb)

Features

• actions context information add clientID (#10339) (416a355), closes #9377
• actions v2 api GA (#10364) (096e92f)
• Actions V2 improvements in console (#9759) (56e0df6), closes #7248
• add custom org ID to AddOrganizationRequest (#9720) (6889d6a), closes /github.com/zitadel/zitadel/discussions/9202#discussioncomment-11929464 #9202
• add Turkish language support (#10198) (25adfd9)
• api: moving organization API resourced based (#9943) (ae1a2e9)
• api: reworking AddOrganization() API call to return all admins (#9900) (7df4f76)
• App API v2 (#10077) (2691dae), closes #9450 #9450
• App Keys API v2 (#10140) (fce9e77), closes #9450 #9450 #9450
• console: Add organization ID filter to organization list (#9823) (2885601), closes #8792
• crypto: support for SHA2 and PHPass password hashes (#9809) (38013d0)
• Display Authentication Method Name on Application Page (#9639) (6aeaa89), closes #9435
• exchange gRPC server implementation to connectRPC (#10145) (9ebf231), closes #9483
• federated logout for SAML IdPs (#9931) (2cf3ef4), closes #9228
• generate webkeys setup step (#10105) (fa9de9a)
• Hosted login translation API (#10011) (28f7218), closes #9850
• implement service ping (#10080) (f93a35c), closes #9869
• initial admin PAT has IAM_LOGIN_CLIENT (#10143) (a02a534), closes #10116
• instance requests implementation for resource API (#9830) (490e4bd), closes #9452
• JWT IdP intent (#9966) (4d66a78), closes #9758
• OIDC: handle logout hint on end_session_endpoint (#10039) (5d2d1d6), closes #9847
• permissions: project member permission filter (#9757) (658ca36)
• project v2beta resource API (#9742) (7eb45c6), closes #9177
• projections: resource counters (#9979) (b9c1cdf)
• typescript: add i18n for all input required messages in Login V2 (#10288) (74e1448)
• user api requests to resource API (#9794) (8fc11a7)
• user profile requests in resource APIs (#10151) (5403be7), closes #9165

Performance Improvements

• eventstore: add instance position index (#9837) (bb56b36)
• improve org and org domain creation (#10232) (fefeaea)
• query: org permission function for resources (#9677) (a2f60f2)
• query: reduce user query duration (#10037) (4df1382)