# Table of Contents
- [ZITADEL Documentation | ZITADEL Docs](#zitadel-documentation-zitadel-docs)
- [APIs V2 (Generally Available) | ZITADEL Docs](#apis-v2-generally-available-zitadel-docs)
- [GRPC Status Codes in ZITADEL | ZITADEL Docs](#grpc-status-codes-in-zitadel-zitadel-docs)
- [Third party sub-processors for ZITADEL | ZITADEL Docs](#third-party-sub-processors-for-zitadel-zitadel-docs)
- [Principles | ZITADEL Docs](#principles-zitadel-docs)
- [Legal Agreements | ZITADEL Docs](#legal-agreements-zitadel-docs)
- [Key Concepts | ZITADEL Docs](#key-concepts-zitadel-docs)
- [ZITADEL API Reference Overview | ZITADEL Docs](#zitadel-api-reference-overview-zitadel-docs)
- [Annex for ZITADEL Enterprise and Support Services | ZITADEL Docs](#annex-for-zitadel-enterprise-and-support-services-zitadel-docs)
- [Zitadel Roadmap | ZITADEL Docs](#zitadel-roadmap-zitadel-docs)
- [Migrate from v1 APIs to v2 APIs | ZITADEL Docs](#migrate-from-v1-apis-to-v2-apis-zitadel-docs)
- [Data Processing Agreement | ZITADEL Docs](#data-processing-agreement-zitadel-docs)
- [ZITADEL - Identity Infrastructure, Simplified](#zitadel-identity-infrastructure-simplified)
- [Configure ZITADEL | ZITADEL Docs](#configure-zitadel-zitadel-docs)
---
# ZITADEL Documentation | ZITADEL Docs
ZITADEL Documentation
=====================
**ZITADEL is the Identity Infrastructure for Developers.**
We provide a hardened, extensible turnkey solution for all your authentication and authorization needs. Instead of building your own login system, use ZITADEL to accelerate your project with features that work out of the box:
* **Secure Login**: Multi-factor authentication (OTP, U2F, Passkeys) and single sign-on (OIDC, SAML, OAuth2).
* **B2B Ready**: First-class multi-tenancy with branding customization and self-service.
* **Auditable**: Exhaustive audit trail of all events.
* **Extensible**: Execute custom code on events (Actions) to fit your unique workflows.
[Get Started](https://zitadel.com/docs#get-started)
----------------------------------------------------
Explore our guides to get up and running with ZITADEL quickly.
[### Quick Start Guide\
\
Learn how to set up ZITADEL in minutes.](https://zitadel.com/docs/guides/start/quickstart)
[### SDKs\
\
Explore our libraries for your favorite languages.](https://zitadel.com/docs/sdk-examples/introduction)
[### Example Apps\
\
Sample applications to help you get started.](https://zitadel.com/docs/examples/introduction)
[### Knowledge Base\
\
Find answers to common ZITADEL questions and issues.](https://help.zitadel.com/)
[Deployment Options](https://zitadel.com/docs#deployment-options)
------------------------------------------------------------------
You can use ZITADEL in two ways:
* **ZITADEL Cloud**: This is our public cloud service. Use the free tier to start in minutes.
* **Self-hosted ZITADEL**: For full control, deploy ZITADEL wherever you prefer.
If you're unsure, consider the generous free tier of [ZITADEL Cloud](https://help.zitadel.com/customer-portal-getting-started)
.
[### ZITADEL Cloud\
\
Choose if you want:\
\
* A turnkey solution that's ready to go\
* Global scalability without the hassle\
* Data-residency compliance](https://help.zitadel.com/customer-portal-getting-started)
[### Self-hosted\
\
Choose if you want:\
\
* Total control over all components\
* Air-gapped or regulated environments\
* Flexibility when deploying updates](https://zitadel.com/docs/self-hosting/deploy/overview)
[Explore Components](https://zitadel.com/docs#explore-components)
------------------------------------------------------------------
Deep dive into the architecture and capabilities of ZITADEL.
[### Concepts\
\
Understand the core principles of ZITADEL.](https://zitadel.com/docs/concepts)
[### APIs\
\
Reference documentation for our REST and gRPC APIs.](https://zitadel.com/docs/apis/introduction)
[### Self-hosting\
\
Learn how to deploy and manage ZITADEL yourself.](https://zitadel.com/docs/self-hosting/deploy/overview)
[### Legal\
\
Terms of service, privacy policy, and more.](https://zitadel.com/docs/legal)
[Community & Support](https://zitadel.com/docs#community-support)
------------------------------------------------------------------
Join the community and get help.
[### Discord\
\
Join our Discord chat to get help from the community and the ZITADEL team.](https://zitadel.com/chat)
[### Github Discussions\
\
Open a discussion on Github.](https://github.com/zitadel/zitadel/discussions)
[### Office Hours\
\
Join our bi-weekly community calls.](https://zitadel.com/office-hours)
[### Contribute\
\
Help us improve ZITADEL and its documentation.](https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.mdx)
Was this page helpful?
### On this page
[Get Started](https://zitadel.com/docs#get-started)
[Deployment Options](https://zitadel.com/docs#deployment-options)
[Explore Components](https://zitadel.com/docs#explore-components)
[Community & Support](https://zitadel.com/docs#community-support)
---
# APIs V2 (Generally Available) | ZITADEL Docs
APIs V2 (Generally Available)
=============================
The v2 APIs are the recommended way to interact with ZITADEL resources. They are resource-based, automatically scope results to the caller's permissions, and replace the context-specific v1 APIs over time.
If a resource you need is not yet available here, use the corresponding [legacy v1 API](https://zitadel.com/docs/apis/introduction#legacy-v1-apis)
for that operation and check the [migration guide](https://zitadel.com/docs/apis/migration_v1_to_v2)
to plan your transition.
Users created with the V2 API have no initial state anymore, so new users are immediately active. Requesting ZITADEL to send a verification email on user creation is still possible.
Was this page helpful?
---
# GRPC Status Codes in ZITADEL | ZITADEL Docs
APIs
GRPC Status Codes in ZITADEL
============================
| GRPC Number | GRPC Code | HTTP Status Code | HTTP Status Text | Description |
| --- | --- | --- | --- | --- |
| 0 | OK | 200 | OK | Not an error; returned on success. |
| 2 | UNKNOWN | 500 | Internal | Unknown error, this is sent if the error could not be identified as one of the errors described below |
| 3 | INVALID\_ARGUMENT | 400 | Bad Request | The client specified an invalid argument. Note that this differs from FAILED\_PRECONDITION. INVALID\_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name). |
| 4 | DEADLINE\_EXCEEDED | 504 | Gateway Timeout | The deadline expired before the operation could complete. |
| 5 | NOT\_FOUND | 404 | Not found | Some requested entity (e.g. user or project) was not found. |
| 6 | ALREADY\_EXISTS | 409 | Conflict | The entity that a client attempted to create (e.g. user or project) already exists. |
| 7 | PERMISSION\_DENIED | 403 | Forbidden | The caller does not have permission to execute the specified operation. |
| 9 | FAILED\_PRECONDITION | 400 | Bad Request | The operation was rejected because the system is not in a state required for the operation's execution. e.g a project that is already deactivated, should be deactivated |
| 12 | UNIMPLEMENTED | 501 | Not Implemented | The operation is not implemented or is not supported/enabled in this service. |
| 13 | INTERNAL | 500 | Internal | Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors. |
| 14 | UNAVAILABLE | 503 | Service Unavailable | The service is currently unavailable. |
| 16 | UNAUTHENTICATED | 401 | Unauthorized | The request does not have valid authentication credentials for the operation. |
[Error details and slugs](https://zitadel.com/docs/apis/statuscodes#error-details-and-slugs)
---------------------------------------------------------------------------------------------
For stable `v2` APIs, services import `zitadel/error/v2/error.proto` so reflection-aware clients can resolve `zitadel.error.v2.ErrorDetail`.
When present, inspect `ErrorDetail.slug` first for programmatic handling. Slugs are stable machine-readable identifiers such as `user.already_exists`.
Use `ErrorDetail.message` for developer diagnostics, not end-user text. Prefer mapping slugs to your own localized messages in clients.
This slug-based handling is currently relevant for backend/domain paths that run with relational-storage-backed logic. Do not assume it for `v1`, `v2beta`, or `v3alpha` APIs or when using a v2 endpoint without having the relational storage feature enabled.
Was this page helpful?
[SCIM v2.0 (Preview)\
\
Manage instance resources using the SCIM v2.0 API for identity and access integration with ZITADEL](https://zitadel.com/docs/apis/scim2)
[Rate Limits (Cloud)\
\
Guidelines and implementation details for API rate limiting to ensure performance and availability of cloud services](https://zitadel.com/docs/legal/policies/rate-limit-policy)
### On this page
[Error details and slugs](https://zitadel.com/docs/apis/statuscodes#error-details-and-slugs)
---
# Third party sub-processors for ZITADEL | ZITADEL Docs
Legal Agreements
Third party sub-processors for ZITADEL
======================================
Last updated on December 5, 2025.
In order to achieve the best possible transparency we publish which sub-processors and services we use to provide ZITADEL and related services. The table shows what activity each entity performs. More information about each activity is provided directly below. This explains the limited processing of customer data the entity is authorized to perform.
We regularly audit all data processing agreements that we have with our sub-processors to guarantee that they adhere to the same level of privacy as ours to protect your personal data.
You can find [the full list of sub-processors in our trust center](https://trust.zitadel.com/subprocessors)
. We try to minimize the number of sub-processors that handle end-user data on our behalf to reduce any vendor related risks. Some providers are used by default, but you can opt out of the default provider and replace the sub-processor by a provider of your choice.
Was this page helpful?
[Data Processing Agreement\
\
ZITADEL's Data Processing Agreement (DPA) regarding the processing of personal data on behalf of customers.](https://zitadel.com/docs/legal/data-processing-agreement)
[Enterprise Agreement\
\
Annex describing commercial support services for ZITADEL Enterprise licenses and support agreements.](https://zitadel.com/docs/legal/annex-support-services)
---
# Principles | ZITADEL Docs
Architecture & Concepts
Principles
==========
[ZITADEL engineering and design principles](https://zitadel.com/docs/concepts/principles#zitadel-engineering-and-design-principles)
------------------------------------------------------------------------------------------------------------------------------------
* Be transparent about your decisions
* Embrace stateless application design
* System of records is the event store
* Everything else needs to be able to be regenerated
* Try not to solve complex problems outside the IAM Domain
* Use a scalable storage for the event store and read models
* Try to be idempotent whenever possible
* Reduce necessity of external systems or dependencies as much as possible
* Embrace automation
* Design API first
* Optimize all components for day-two operations
* Use only open source projects with permissive licenses
* Don't roll your own crypto algorithm
* Embrace (industry) standard as much as possible
* Make use of platform features
* Be able to run with a CDN and WAF
* Releases utilized semantic versioning and release whenever feasible
Was this page helpful?
[Secrets\
\
How ZITADEL manages and protects secrets through encryption, hashing, and rotation mechanisms.](https://zitadel.com/docs/concepts/architecture/secrets)
[Overview\
\
Implement Event Sourcing with ZITADEL's Event Store to track changes and derive system state from immutable events](https://zitadel.com/docs/concepts/eventstore/overview)
### On this page
[ZITADEL engineering and design principles](https://zitadel.com/docs/concepts/principles#zitadel-engineering-and-design-principles)
---
# Legal Agreements | ZITADEL Docs
Legal Agreements
================
[### Terms Of Service](https://zitadel.com/docs/legal/terms-of-service)
[### Data Processing Agreement](https://zitadel.com/docs/legal/data-processing-agreement)
[### Subprocessors](https://zitadel.com/docs/legal/subprocessors)
[### Annex Support Services](https://zitadel.com/docs/legal/annex-support-services)
[### Service Description](https://zitadel.com/docs/legal/service-description)
[### Policies](https://zitadel.com/docs/legal/policies)
Was this page helpful?
---
# Key Concepts | ZITADEL Docs
Key Concepts
============
[### Instance](https://zitadel.com/docs/concepts/structure/instance)
[### Organizations Overview](https://zitadel.com/docs/guides/manage/console/organizations-overview)
[### Projects Overview](https://zitadel.com/docs/guides/manage/console/projects-overview)
[### Applications Overview](https://zitadel.com/docs/guides/manage/console/applications-overview)
[### Users Overview](https://zitadel.com/docs/guides/manage/console/users-overview)
[### Administrators](https://zitadel.com/docs/concepts/structure/administrators)
Was this page helpful?
---
# ZITADEL API Reference Overview | ZITADEL Docs
APIs
ZITADEL API Reference Overview
==============================
ZITADEL exposes all features via different gRPC and REST APIs and provides SDKs for popular languages and frameworks.
The [OpenID Connect & OAuth endpoints](https://zitadel.com/docs/apis/openidoauth/endpoints)
and [SAML 2.0 endpoints](https://zitadel.com/docs/apis/saml/endpoints)
are implemented and exposed according to the specific standards. Managing resources such as users, organizations, instances, or settings must be done with the different [ZITADEL APIs](https://zitadel.com/docs/apis/introduction#zitadel-apis)
.
[Actions](https://zitadel.com/docs/guides/manage/console/actions-overview)
allow extending ZITADEL with custom code to change default behaviors or calling external systems.
[Authentication & Authorization](https://zitadel.com/docs/apis/introduction#authentication-authorization)
----------------------------------------------------------------------------------------------------------
### [Authentication for users (interactive)](https://zitadel.com/docs/apis/introduction#authentication-for-users-interactive)
ZITADEL implements industry standards such as OpenID Connect, OAuth 2.0, or SAML for authentication. Please refer to our guides on how to [authenticate users](https://zitadel.com/docs/guides/integrate/login/login-users)
through an interactive authentication process.
For user authentication on devices with limited accessibility (eg, SmartTV, Smartwatch, etc.) use the [device authorization grant](https://zitadel.com/docs/guides/integrate/login/oidc/device-authorization)
.
Additionally, you can use the [session API](https://zitadel.com/docs/reference/api/session)
to authenticate users, for example, by building a [custom login UI](https://zitadel.com/docs/guides/integrate/login-ui)
.
### [Authenticate service accounts](https://zitadel.com/docs/apis/introduction#authenticate-service-accounts)
Service accounts allow for machine-to-machine (M2M) communication. Follow the guides to learn how to [authenticate service accounts](https://zitadel.com/docs/guides/integrate/service-accounts/authenticate-service-accounts)
.
Accessing the ZITADEL APIs through a service account might require additional steps, please follow the guide on how to [access ZITADEL APIs](https://zitadel.com/docs/guides/integrate/zitadel-apis/access-zitadel-apis)
to include the correct audience scope in your requests.
### [OpenID Connect & OAuth](https://zitadel.com/docs/apis/introduction#open-id-connect-o-auth)
* [OpenID Connect endpoints](https://zitadel.com/docs/apis/openidoauth/endpoints)
definition
* Standard and reserved [scopes reference](https://zitadel.com/docs/apis/openidoauth/scopes)
* Standard, custom, and reserved [claims reference](https://zitadel.com/docs/apis/openidoauth/claims)
The [OIDC Playground](https://zitadel.com/playgrounds/oidc)
is for testing OpenID authentication requests and their parameters.
### [SAML 2.0](https://zitadel.com/docs/apis/introduction#saml-2-0)
* [SAML 2.0 endpoints](https://zitadel.com/docs/apis/saml/endpoints)
definition
* [Custom attributes](https://github.com/zitadel/actions/blob/main/examples/set_custom_attribute.js)
can be added with an action
### [Session-based and custom login](https://zitadel.com/docs/apis/introduction#session-based-and-custom-login)
For building a custom login flow, you have access to purpose-built v2 APIs:
* [Create or update a session](https://zitadel.com/docs/reference/api/session/zitadel.session.v2.SessionService.CreateSession)
to authenticate users step by step
* [Get OIDC auth request details](https://zitadel.com/docs/reference/api/oidc/zitadel.oidc.v2.OIDCService.GetAuthRequest)
when acting as an OIDC provider
* [Get SAML request details](https://zitadel.com/docs/reference/api/saml/zitadel.saml.v2.SAMLService.GetSAMLRequest)
when acting as a SAML provider
User role assignments can be [retrieved as roles from our APIs](https://zitadel.com/docs/guides/integrate/retrieve-user-roles)
.
Refer to our guide to learn how to [build your own login UI](https://zitadel.com/docs/guides/integrate/login-ui)
[ZITADEL APIs](https://zitadel.com/docs/apis/introduction#zitadel-ap-is)
-------------------------------------------------------------------------
**Use the [v2 APIs](https://zitadel.com/docs/apis/v2)
for all new integrations.** They are the recommended, resource-based API surface for ZITADEL and where all new development is happening. The v1 APIs are legacy: fully supported and still required in some places, but not being extended.
If the resource you need is not yet available in v2, use the corresponding legacy v1 API for that operation and check the [migration guide](https://zitadel.com/docs/apis/migration_v1_to_v2)
to plan your transition.
[APIs v2 (resource-based)](https://zitadel.com/docs/apis/introduction#ap-is-v-2-resource-based)
------------------------------------------------------------------------------------------------
ZITADEL provides v2 APIs for the following resources:
* [User](https://zitadel.com/docs/reference/api/user)
— manage users and their authentication methods
* [Session](https://zitadel.com/docs/reference/api/session)
— create and manage user sessions
* [Organization](https://zitadel.com/docs/reference/api/org)
— manage organizations
* [Instance](https://zitadel.com/docs/reference/api/instance)
— manage your ZITADEL instance
* [Project](https://zitadel.com/docs/reference/api/project)
— manage projects and granted projects
* [Application](https://zitadel.com/docs/reference/api/application)
— manage OIDC, SAML, and API applications
* [IDP](https://zitadel.com/docs/reference/api/idp)
— manage identity providers
* [Group](https://zitadel.com/docs/reference/api/group)
— manage user groups
* [Settings](https://zitadel.com/docs/reference/api/settings)
— read login and instance settings
* [Feature](https://zitadel.com/docs/reference/api/feature)
— manage feature flags
* [Authorization](https://zitadel.com/docs/reference/api/authorization)
— check and manage user permissions
* [Action](https://zitadel.com/docs/reference/api/action)
— manage execution targets and action flows
* [WebKey](https://zitadel.com/docs/reference/api/webkey)
— manage signing keys
* [OIDC](https://zitadel.com/docs/reference/api/oidc)
— handle OIDC authorization flows (used when building a custom login UI)
* [SAML](https://zitadel.com/docs/reference/api/saml)
— handle SAML authorization flows (used when building a custom login UI)
Not finding a resource here? It has not yet been migrated to v2 — use the legacy v1 APIs below for that operation.
[Legacy v1 APIs](https://zitadel.com/docs/apis/introduction#legacy-v-1-ap-is)
------------------------------------------------------------------------------
The following APIs predate the v2 resource-based design. They are still fully supported and required for capabilities not yet covered by v2, but they are no longer being extended. If you are building something new, check the v2 section above first.
Looking to move an existing integration off v1? See the [v1 to v2 migration guide](https://zitadel.com/docs/apis/migration_v1_to_v2)
.
### [Authentication](https://zitadel.com/docs/apis/introduction#authentication)
The Auth API covers operations on the currently authenticated user. The user is identified from the `sub` claim in the access token.
For new integrations, prefer the [User v2 API](https://zitadel.com/docs/reference/api/user)
and [Session v2 API](https://zitadel.com/docs/reference/api/session)
which provide the same capabilities in a resource-based design.
#### [Auth GRPC](https://zitadel.com/docs/apis/introduction#auth-grpc)
Endpoint: `${CUSTOM_DOMAIN}/zitadel.auth.v1.AuthService/`
Definition: [Auth Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/auth.proto)
#### [Auth REST](https://zitadel.com/docs/apis/introduction#auth-rest)
Endpoint: `${CUSTOM_DOMAIN}/auth/v1/`
API Reference: [OpenAPI Docs](https://zitadel.com/docs/reference/api/auth)
### [Management](https://zitadel.com/docs/apis/introduction#management)
The Management API lets systems read and mutate resources within an organization — users, projects, applications, roles, and more. The target organization is determined by the `x-zitadel-orgid` request header, or falls back to the organization of the authenticated user.
For new integrations, prefer the [User v2 API](https://zitadel.com/docs/reference/api/user)
for user management, which handles both instance-level and organization-level access automatically based on caller permissions.
#### [Mgmt GRPC](https://zitadel.com/docs/apis/introduction#mgmt-grpc)
Endpoint: `${CUSTOM_DOMAIN}/zitadel.management.v1.ManagementService/`
Definition: [Management Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/management.proto)
#### [Mgmt REST](https://zitadel.com/docs/apis/introduction#mgmt-rest)
Endpoint: `${CUSTOM_DOMAIN}/management/v1/`
API Reference: [OpenAPI Docs](https://zitadel.com/docs/reference/api/management)
### [Administration](https://zitadel.com/docs/apis/introduction#administration)
This API is intended to configure and manage one ZITADEL instance itself.
#### [Admin GRPC](https://zitadel.com/docs/apis/introduction#admin-grpc)
Endpoint: `${CUSTOM_DOMAIN}/zitadel.admin.v1.AdminService/`
Definition: [Admin Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/admin.proto)
#### [Admin REST](https://zitadel.com/docs/apis/introduction#admin-rest)
Endpoint: `${CUSTOM_DOMAIN}/admin/v1/`
API Reference: [OpenAPI Docs](https://zitadel.com/docs/reference/api/admin)
### [System](https://zitadel.com/docs/apis/introduction#system)
This API is intended to manage the different ZITADEL instances within the system.
Checkout the guide how to [access the ZITADEL System API](https://zitadel.com/docs/guides/integrate/zitadel-apis/access-zitadel-system-api)
.
#### [System GRPC](https://zitadel.com/docs/apis/introduction#system-grpc)
Endpoint: `${CUSTOM_DOMAIN}/zitadel.system.v1.SystemService/`
Definition: [System Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/system.proto)
#### [System REST](https://zitadel.com/docs/apis/introduction#system-rest)
Endpoint: `${CUSTOM_DOMAIN}/system/v1/`
API Reference: [OpenAPI Docs](https://zitadel.com/docs/reference/api/system)
### [Assets](https://zitadel.com/docs/apis/introduction#assets)
The Assets API allows you to up- and download all kinds of assets. This can be files such as logos, fonts or user avatar.
#### [Assets REST](https://zitadel.com/docs/apis/introduction#assets-rest)
Endpoint: `${CUSTOM_DOMAIN}/assets/v1/`
Definition: [Assets](https://zitadel.com/docs/apis/assets/assets)
[Client libraries & schemas](https://zitadel.com/docs/apis/introduction#client-libraries-schemas)
--------------------------------------------------------------------------------------------------
ZITADEL publishes [official and community-supported SDKs](https://zitadel.com/docs/sdk-examples/introduction)
for multiple languages and frameworks. All API services are defined as [proto definitions on GitHub](https://github.com/zitadel/zitadel/tree/main/proto/zitadel)
— most languages let you generate a type-safe client directly from them.
[Domains](https://zitadel.com/docs/apis/introduction#domains)
--------------------------------------------------------------
ZITADEL hosts everything under a single domain: `{instance}.zitadel.cloud` or your Custom Domain `${CUSTOM_DOMAIN}`
The domain is used as the OIDC issuer and as the base URL for the gRPC and REST APIs, the Management Console (`${CUSTOM_DOMAIN}/ui/console/`), and the hosted Login UI (`${CUSTOM_DOMAIN}/ui/v2/login`).
Are you self-hosting and having troubles with _Instance not found_ errors? [Check out this page](https://zitadel.com/docs/self-hosting/manage/custom-domain)
.
[API path prefixes](https://zitadel.com/docs/apis/introduction#api-path-prefixes)
----------------------------------------------------------------------------------
If you run ZITADEL on a Custom Domain, you may want to reuse that domain for other applications. For easy copying to your reverse proxy configuration, here is the list of URL path prefixes, ZITADEL uses.
# v2 APIs (recommended for new integrations)
# REST (HTTP/JSON transcoding):
/v2/
# gRPC + Connect protocol (binary or JSON via connectRPC):
/zitadel.action.v2.ActionService/
/zitadel.application.v2.ApplicationService/
/zitadel.authorization.v2.AuthorizationService/
/zitadel.feature.v2.FeatureService/
/zitadel.group.v2.GroupService/
/zitadel.idp.v2.IdentityProviderService/
/zitadel.instance.v2.InstanceService/
/zitadel.oidc.v2.OIDCService/
/zitadel.org.v2.OrganizationService/
/zitadel.project.v2.ProjectService/
/zitadel.saml.v2.SAMLService/
/zitadel.session.v2.SessionService/
/zitadel.settings.v2.SettingsService/
/zitadel.user.v2.UserService/
/zitadel.webkey.v2.WebKeyService/
# v2beta — kept for backward compatibility, use /v2/ for new work
/v2beta/
# Legacy v1 APIs
/zitadel.admin.v1.AdminService/
/admin/v1/
/zitadel.auth.v1.AuthService/
/auth/v1/
/zitadel.management.v1.ManagementService/
/management/v1/
/zitadel.system.v1.SystemService/
/system/v1/
/assets/v1/
# OpenID Connect, OAuth 2.0, SAML 2.0 & standards
/oidc/v1/
/saml/v2/
/oauth/v2/
/device
/.well-known/openid-configuration
/openapi/
/idps/callback
# UIs
/ui/console/ # Management Console (Angular admin UI)
/ui/v2/login # Login UI v2 (Next.js; routes to a separate container in self-hosted deployments)
/ui/login/ # Login UI v1 (legacy, built into the ZITADEL binary)
[Postman Collection (Beta)](https://zitadel.com/docs/apis/introduction#postman-collection-beta)
------------------------------------------------------------------------------------------------
We published an official Postman collection to help you explore and test the ZITADEL APIs.
The collection is organized by services and includes a script to automatically authenticate requests. Before using it, make sure to configure the required environment variables in Postman:
| Variable Name | Description |
| --- | --- |
| `protocol` | **http** for local testing, or **https** for cloud/self hosted instances |
| `custom_domain` | The domain of your Zitadel instance. |
| `service_client_id` | Client ID of service account with **IAM\_OWNER** role in your Zitadel instance. |
| `service_client_secret` | Client secret for the service account. |
| `api_client_id` | Client ID of an API application. |
| `api_client_secret` | Client secret for the API application. |
| `project_id` | A project ID within your Zitadel instance. |
[Fork the Postman Collection](https://app.getpostman.com/run-collection/44392838-6417c238-b9b9-4334-bef0-233ae38cbc51?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D44392838-6417c238-b9b9-4334-bef0-233ae38cbc51%26entityType%3Dcollection%26workspaceId%3D54ef8cdd-5ea3-4f31-89f6-20720b45528c)
This release is currently in **beta**, and we welcome your feedback to improve it.
Was this page helpful?
[Customer Support\
\
Submit a support request to ZITADEL's customer portal with required information for timely assistance.](https://zitadel.com/docs/guides/manage/cloud/support)
[User API\
\
Explore the User API operation in the ZITADEL API. Learn about request parameters, response schemas, and integration details for this endpoint.](https://zitadel.com/docs/reference/api/user)
### On this page
[Authentication & Authorization](https://zitadel.com/docs/apis/introduction#authentication-authorization)
[Authentication for users (interactive)](https://zitadel.com/docs/apis/introduction#authentication-for-users-interactive)
[Authenticate service accounts](https://zitadel.com/docs/apis/introduction#authenticate-service-accounts)
[OpenID Connect & OAuth](https://zitadel.com/docs/apis/introduction#open-id-connect-o-auth)
[SAML 2.0](https://zitadel.com/docs/apis/introduction#saml-2-0)
[Session-based and custom login](https://zitadel.com/docs/apis/introduction#session-based-and-custom-login)
[ZITADEL APIs](https://zitadel.com/docs/apis/introduction#zitadel-ap-is)
[APIs v2 (resource-based)](https://zitadel.com/docs/apis/introduction#ap-is-v-2-resource-based)
[Legacy v1 APIs](https://zitadel.com/docs/apis/introduction#legacy-v-1-ap-is)
[Authentication](https://zitadel.com/docs/apis/introduction#authentication)
[Auth GRPC](https://zitadel.com/docs/apis/introduction#auth-grpc)
[Auth REST](https://zitadel.com/docs/apis/introduction#auth-rest)
[Management](https://zitadel.com/docs/apis/introduction#management)
[Mgmt GRPC](https://zitadel.com/docs/apis/introduction#mgmt-grpc)
[Mgmt REST](https://zitadel.com/docs/apis/introduction#mgmt-rest)
[Administration](https://zitadel.com/docs/apis/introduction#administration)
[Admin GRPC](https://zitadel.com/docs/apis/introduction#admin-grpc)
[Admin REST](https://zitadel.com/docs/apis/introduction#admin-rest)
[System](https://zitadel.com/docs/apis/introduction#system)
[System GRPC](https://zitadel.com/docs/apis/introduction#system-grpc)
[System REST](https://zitadel.com/docs/apis/introduction#system-rest)
[Assets](https://zitadel.com/docs/apis/introduction#assets)
[Assets REST](https://zitadel.com/docs/apis/introduction#assets-rest)
[Client libraries & schemas](https://zitadel.com/docs/apis/introduction#client-libraries-schemas)
[Domains](https://zitadel.com/docs/apis/introduction#domains)
[API path prefixes](https://zitadel.com/docs/apis/introduction#api-path-prefixes)
[Postman Collection (Beta)](https://zitadel.com/docs/apis/introduction#postman-collection-beta)
---
# Annex for ZITADEL Enterprise and Support Services | ZITADEL Docs
Legal Agreements
Annex for ZITADEL Enterprise and Support Services
=================================================
Last updated on November 15, 2023
This annex of the [Framework Agreement](https://zitadel.com/docs/legal/terms-of-service)
describes the commercial support services (**Support Services**, **Enterprise License**, or **Enterprise Agreement**) for units of ZITADEL software products (**Unit**), if not otherwise defined a Unit refers to a is a single, dedicated setup of an application or service covered under an Enterprise agreement.
The customer relationship (**Framework Agreement** or **The Agreement**) is created by the **Customer** (**"you"**) by accepting a **Purchase Order** (**"PO"**) for the specified Support Services (**Booking**). Jointly you and ZITADEL will be referred to as **the Parties**. The terms of service (**"TOS"**) outlined in this document establish the most important points of this Framework Agreement – independently of the use of any other services.
### [Term](https://zitadel.com/docs/legal/annex-support-services#term)
Coverage under this Agreement will start with Booking of Support Services, for a minimum period of 12 months. Support Services agreements will automatically renew for additional one-year term upon submission of a purchase order for renewal, unless either you or ZITADEL provides written notice (E-Mail sufficient) of termination of any such term. Each renewal will be at ZITADEL's then-current rate. In the event that you accesses ZITADEL Support services in any way after the Agreement has expired or been terminated, you will continue to be bound by this Agreement, which will continue to apply to the services after such expiration or termination.
### [Service review](https://zitadel.com/docs/legal/annex-support-services#service-review)
If not otherwise agreed, ZITADEL offers a yearly review meeting with you to discuss the service quality and any feedback you might have. We are not required to participate in the meeting after the term has expired.
[Your obligations](https://zitadel.com/docs/legal/annex-support-services#your-obligations)
-------------------------------------------------------------------------------------------
### [Maintenance of units](https://zitadel.com/docs/legal/annex-support-services#maintenance-of-units)
You will ensure that units eligible for Support Service are maintained and upgraded frequently. If you operate units with a release date older than 180 days since our latest stable release, the term is continued but ZITADEL is not required to handle any support request for that unit until the units are upgraded and re-certified.
### [Support Process](https://zitadel.com/docs/legal/annex-support-services#support-process)
You will ensure to follow the support process, especially provide all required initial information to the issue, as outlined in the [Annex](https://zitadel.com/docs/legal/service-description/support-services)
to this document.
### [Training of support staff](https://zitadel.com/docs/legal/annex-support-services#training-of-support-staff)
You will ensure regular training of your support staff. Your support staff must be able to provide the required information for support issues to us, and thus requires access and up-to-date knowledge of the services.
Initial know-how transfer for the services will be organized in training sessions conducted by us. We can provide knowledge sessions throughout the term to train newly onboarded staff, update your support staff about important updates, or refresh knowledge in specified areas. In case we notice insufficient quality of support requests from Customers, we will propose appropriate training sessions.
[Financial](https://zitadel.com/docs/legal/annex-support-services#financial)
-----------------------------------------------------------------------------
### [Lapsed Service Fee](https://zitadel.com/docs/legal/annex-support-services#lapsed-service-fee)
In case the term of the Support Service contract has expired within 1 to 180 days, you will be required to pay a Lapsed Service fee in addition to purchasing and activating a one-year renewal contract term at the then-current fee and conditions. The renewal term's start date will also be backdated to begin coverage from the service's original expiration date.
Please contact us for current fees.
### [Recertification Fee](https://zitadel.com/docs/legal/annex-support-services#recertification-fee)
Recertification of a unit, to be covered under Support Services, is required for:
* units for which Support Services have been expired for more than 180 days
* units that run a release that is older than 180 days from the products most recent stable release
* requests for support on products and services purchased or supported from non-authorized resellers
Recertification of a unit requires payment of a Recertification Fee which results in a checkup of the unit by ZITADEL. The unit will be inspected to assess its condition and eligibility for service coverage.
Please contact us for current fees.
### [Disaster recovery](https://zitadel.com/docs/legal/annex-support-services#disaster-recovery)
You are solely responsible to ensure appropriate backup and disaster recovery of Units managed by you. Any liability for damages, indirect or direct, in case of data loss is explicitly rejected.
### [Amendments](https://zitadel.com/docs/legal/annex-support-services#amendments)
We are entitled to unilaterally amend these TOS at any time. The current version is accessible via our website. We will inform you of any amendments via email. These amendments shall be considered as accepted upon booking additional services or at the latest after 30 days. In the case of a rejection on your part we reserve the right to terminate the Framework Agreement.
Was this page helpful?
[Third Party Sub-Processors\
\
List of third-party sub-processors and services used by ZITADEL to provide its identity and authentication services.](https://zitadel.com/docs/legal/subprocessors)
[Service description\
\
Description of services and service levels for ZITADEL Cloud and Enterprise subscriptions.](https://zitadel.com/docs/legal/service-description/cloud-service-description)
### On this page
[Term](https://zitadel.com/docs/legal/annex-support-services#term)
[Service review](https://zitadel.com/docs/legal/annex-support-services#service-review)
[Your obligations](https://zitadel.com/docs/legal/annex-support-services#your-obligations)
[Maintenance of units](https://zitadel.com/docs/legal/annex-support-services#maintenance-of-units)
[Support Process](https://zitadel.com/docs/legal/annex-support-services#support-process)
[Training of support staff](https://zitadel.com/docs/legal/annex-support-services#training-of-support-staff)
[Financial](https://zitadel.com/docs/legal/annex-support-services#financial)
[Lapsed Service Fee](https://zitadel.com/docs/legal/annex-support-services#lapsed-service-fee)
[Recertification Fee](https://zitadel.com/docs/legal/annex-support-services#recertification-fee)
[Disaster recovery](https://zitadel.com/docs/legal/annex-support-services#disaster-recovery)
[Amendments](https://zitadel.com/docs/legal/annex-support-services#amendments)
---
# Zitadel Roadmap | ZITADEL Docs
Product, Releases & Support
Zitadel Roadmap
===============
Identity has changed significantly since Zitadel was first built.
Over the last few years, we've worked with customers operating everything from modern SaaS applications to large enterprise platforms serving millions of users. As those customers have grown, we've seen the same platform take on increasingly complex identity challenges—from enterprise federation and global deployments to machine identities and AI agents.
The next iteration of Zitadel is built so our customers can continue solving tomorrow's identity challenges on the same platform they choose today. That requires a more flexible foundation—one that supports new identity models, web-scale deployments, and emerging identity patterns without accumulating complexity over time.
The roadmap below outlines the strategic platform investments we're making over the coming releases and the customer capabilities they unlock.
_This roadmap reflects our current strategic direction rather than a fixed release plan. As we continue validating the next iteration of Zitadel with customers and the community, priorities and sequencing may evolve._
[**What this means for existing customers**](https://zitadel.com/docs/product/roadmap#what-this-means-for-existing-customers)
------------------------------------------------------------------------------------------------------------------------------
The next iteration of Zitadel is an evolution of the platform, not a replacement.
Existing V4 deployments remain fully supported while we introduce the next iteration incrementally. Zitadel V4 will continue to be supported for at least 12 months, with security updates, critical customer issues, and targeted improvements continuing throughout this period.
Many of the capabilities our customers have been asking for require architectural changes that go beyond incremental improvements to the current platform. Those capabilities will therefore be introduced as part of the next iteration of Zitadel, while V4 continues to receive security updates, bug fixes, and targeted improvements where appropriate.
As new platform capabilities become available, we'll provide migration tooling and guidance so teams can adopt them incrementally rather than through a disruptive migration. Our goal is to make adoption predictable and low risk, whether you're running Zitadel Cloud or self-hosting your own deployment.
[**Strategic Roadmap**](https://zitadel.com/docs/product/roadmap#strategic-roadmap)
------------------------------------------------------------------------------------
The next iteration of Zitadel will be delivered incrementally, with each investment building on the foundations established by the previous one. The roadmap below outlines the major platform capabilities we're investing in and our current target horizon for each.
| Strategic investment | Key capabilities | Timeline |
| --- | --- | --- |
| Instant authentication | Working authentication in under a minute, local identity runtime, CLI-first developer workflow | [In preview](https://zitadel.com/blog/next-zitadel-preview) |
| [Flexible Identity](https://zitadel.com/docs/product/roadmap#flexible-identity) | User Schemas, composable authentication, identity as code, instant application updates | H2 2026 |
| [Enterprise Platform](https://zitadel.com/docs/product/roadmap#enterprise-platform) | One identity model, unified configuration, web-scale identity | H2 2026 |
| [AI-Native Identity](https://zitadel.com/docs/product/roadmap#ai-native-identity) | First-class AI identities, delegated authority, AI identity lifecycle | H2 2026 |
| [Identity Observability](https://zitadel.com/docs/product/roadmap#identity-observability) | End-to-end identity visibility and audit trail, identity intelligence | H1 2027 |
| Production rollout | Migration tooling, production readiness, Cloud & self-hosted adoption | 2027 |
[**Flexible Identity**](https://zitadel.com/docs/product/roadmap#flexible-identity)
------------------------------------------------------------------------------------
Every application models identity differently, and those requirements continue to evolve over time. As products grow, new user types emerge, registration flows become more sophisticated, and different applications require different identity models.
The next iteration of Zitadel introduces a more flexible foundation for modelling identity. User schemas become the source of truth for identity, while composable authentication components and identity-as-code make authentication feel like a natural part of your application development workflow.
**Strategic investments**
* User Schemas
* Identity-as-code
* Composable authentication components
* Live development preview
* Versioned identity configuration
**Customer outcomes**
* Authentication adapts to your application.
* Identity models evolve without disruptive migrations.
* Identity becomes part of your normal development workflow.
[**Enterprise Platform**](https://zitadel.com/docs/product/roadmap#enterprise-platform)
----------------------------------------------------------------------------------------
Enterprise identity becomes increasingly complex as products grow. Every new customer brings different identity providers, organisation-specific requirements, compliance needs, and operational expectations. Over time, those differences can turn into multiple configuration models, overlapping policies, and an increasing number of special cases.
The next iteration of Zitadel simplifies that foundation. By moving towards a more unified platform model, we're making enterprise identity easier to operate while building the foundations required for web-scale deployments.
**Strategic investments**
* Unified identity model
* Unified configuration
* Web-scale architecture
* Regional deployment foundations
**Customer outcomes**
* Onboard enterprise customers without accumulating operational complexity.
* Scale from your first enterprise customer to global deployments on the same platform.
* Reduce configuration overhead while supporting increasingly complex identity requirements.
[**AI-Native Identity**](https://zitadel.com/docs/product/roadmap#ai-native-identity)
--------------------------------------------------------------------------------------
Identity is no longer limited to human users and traditional service accounts. AI agents are increasingly authenticating, accessing APIs, performing delegated actions, and interacting with enterprise systems on behalf of users.
The next iteration of Zitadel treats AI agents as first-class identities. Rather than adapting existing human identity models to new use cases, we're building identity, delegation, and lifecycle management around the way AI agents actually operate.
**Strategic investments**
* Agent identities
* Delegated authority
* Agent lifecycle management
* Scoped permissions
* Agent-to-agent interactions
**Customer outcomes**
* Govern AI agents with the same confidence as human identities.
* Secure delegated actions without introducing new trust models.
* Build AI-native applications on an identity platform designed for autonomous systems.
[**Identity Observability**](https://zitadel.com/docs/product/roadmap#identity-observability)
----------------------------------------------------------------------------------------------
As organisations adopt more distributed identity models, understanding who did what—and under whose authority—becomes significantly more difficult. A single request may involve a human user, an AI agent, delegated authority, enterprise federation, and multiple systems before it reaches your application.
The next iteration of Zitadel brings that visibility closer to the identity layer itself. By connecting authentication, authorization, sessions, delegation, and identity activity, we're building a more complete view of identity across your systems.
**Strategic investments**
* Identity observability
* End-to-end identity context
* Identity activity timeline
* Delegation tracking
* Identity intelligence
**Customer outcomes**
* Understand who performed an action, through which identity, and under whose authority.
* Investigate identity-related incidents more quickly with complete identity context.
* Improve governance, security, and operational visibility across human, machine, and AI identities.
[**Migration and Adoption**](https://zitadel.com/docs/product/roadmap#migration-and-adoption)
----------------------------------------------------------------------------------------------
V2 has already reached end-of-life (EOL). We'll be sharing V3's EOL timeline and upgrade guidance soon to help customers plan their upgrade with confidence. During the transition, community contributions remain an important part of Zitadel. If you're maintaining a V4 deployment and would like to contribute fixes or improvements, we'll continue reviewing and working with contributors wherever those changes align with the long-term direction of the platform.
Before starting a larger contribution, we encourage you to open a GitHub issue first. This helps us validate the approach, share any relevant roadmap context, and ensure the work aligns with the direction of the platform.
**Strategic investments**
* Incremental migration
* Compatibility guidance
* Migration tooling
* Cloud & self-hosted alignment
* Long-term platform stability
**Customer outcomes**
* Adopt new platform capabilities without disrupting existing deployments.
* Plan migration based on your own priorities and timelines.
* Continue building on the same platform as your identity requirements evolve.
Was this page helpful?
[Limit access to management console\
\
Guidelines and strategies for restricting user access to the ZITADEL Management Console to enforce custom application-level user management.](https://zitadel.com/docs/guides/solution-scenarios/restrict-console)
[Troubleshoot\
\
Common troubleshooting steps for ZITADEL, including error messages, login issues, and community support resources.](https://zitadel.com/docs/support/troubleshooting)
### On this page
[**What this means for existing customers**](https://zitadel.com/docs/product/roadmap#what-this-means-for-existing-customers)
[**Strategic Roadmap**](https://zitadel.com/docs/product/roadmap#strategic-roadmap)
[**Flexible Identity**](https://zitadel.com/docs/product/roadmap#flexible-identity)
[**Enterprise Platform**](https://zitadel.com/docs/product/roadmap#enterprise-platform)
[**AI-Native Identity**](https://zitadel.com/docs/product/roadmap#ai-native-identity)
[**Identity Observability**](https://zitadel.com/docs/product/roadmap#identity-observability)
[**Migration and Adoption**](https://zitadel.com/docs/product/roadmap#migration-and-adoption)
---
# Migrate from v1 APIs to v2 APIs | ZITADEL Docs
APIsCore ResourcesV1
Migrate from v1 APIs to v2 APIs
===============================
This guide helps you migrate from our v1 APIs to v2 APIs. Use v2 where the required resource is available, and keep using v1 for capabilities that are not yet migrated. The sections below explain the architectural changes and the concrete migration considerations.
[The v1 Approach: Use-Case Based APIs](https://zitadel.com/docs/apis/migration_v1_to_v2#the-v-1-approach-use-case-based-ap-is)
-------------------------------------------------------------------------------------------------------------------------------
Our v1 API was structured around use cases, meaning we provided distinct APIs tailored to different user roles:
* Auth API: For authenticated users.
* Management API: For administrators of an organization.
* Admin API: For administrators of an instance.
* System API: For managing multiple instances.
While this approach served its initial purpose, it presented a few challenges. Developers often found it difficult to determine which specific API endpoint to use for their needs. Additionally, this model sometimes led to redundant implementations of similar functionalities across different APIs – for example, listing users might have existed in slightly different forms for an instance context versus an organization context. This often required more extensive reading of documentation and further explanation to ensure correct usage.
[The v2 Approach: A Resource-Based API](https://zitadel.com/docs/apis/migration_v1_to_v2#the-v-2-approach-a-resource-based-api)
--------------------------------------------------------------------------------------------------------------------------------
With our v2 API, we introduce a resource-based architecture. This means instead of organizing by user type, we now structure our API around logical resources, such as:
* Users API
* Instance API
* Organization API
* And more...
A key improvement in v2 is how context and permissions are handled. The data you receive from an endpoint will now automatically be scoped based on the role and permissions of the authenticated user.
For example:
* An instance administrator calling a GET /users endpoint will receive a list of all users within that instance.
* An organization administrator calling the exact same GET /users endpoint will receive a list of users belonging only to their specific organization.
[Why the Change](https://zitadel.com/docs/apis/migration_v1_to_v2#why-the-change)
----------------------------------------------------------------------------------
The primary goals behind this architectural shift are to make our API:
* More Intuitive: Finding the right endpoint should feel natural. If you want to interact with users, you look at the Users API.
* Self-Explanatory: The structure itself guides you, reducing the need to sift through extensive documentation to understand which API "hat" you need to wear.
* Developer-Friendly: A cleaner, more consistent API surface means faster integration and less room for confusion.
We're confident that these changes will significantly enhance your experience working with our platform. The following sections will detail the specific resources that have been migrated and outline any changes you'll need to be aware of.
[Resource Migration](https://zitadel.com/docs/apis/migration_v1_to_v2#resource-migration)
------------------------------------------------------------------------------------------
This section details the migrated resources, including any breaking changes and other important considerations for your transition from v1 to v2.
### [General Changes](https://zitadel.com/docs/apis/migration_v1_to_v2#general-changes)
#### [Sunsetting OpenAPI/REST Support in Favor of Connect RPC](https://zitadel.com/docs/apis/migration_v1_to_v2#sunsetting-open-api-rest-support-in-favor-of-connect-rpc)
While our v1 API already offered gRPC, it also provided a parallel REST/OpenAPI interface for applications who preferred making traditional HTTP calls.
In our v2 API, we are consolidating our efforts to provide a more streamlined and efficient development experience. The primary change is the removal of the OpenAPI/REST interface. We will now exclusively support interaction with our gRPC services directly or through [Connect RPC](https://connectrpc.com/)
.
Connect RPC is being introduced as the new, official way to interact with our gRPC services using familiar, plain HTTP/1.1. It effectively replaces the previous REST gateway.
For teams already using gRPC, your transition will be minimal. For teams who were using the v1 REST API, migrating to v2 will involve adopting one of the following methods:
* Native gRPC: For the highest performance and to leverage features like bidirectional streaming.
* Connect RPC: For making CRUD-like (Create, Read, Update, Delete) calls over HTTP. This is the recommended path for most applications migrating from our v1 REST API.
A significant advantage of this new architecture remains the automatic generation of client libraries. Based on our .proto service definitions, you can generate type-safe applications for your specific programming language, whether you use native gRPC or Connect RPC. This eliminates the need to write boilerplate code for handling HTTP requests and parsing responses, leading to a more streamlined and less error-prone development process.
#### [Contextual Information in the Request Body](https://zitadel.com/docs/apis/migration_v1_to_v2#contextual-information-in-the-request-body)
A key change in v2 is that contextual data, like organization\_id, must now be sent in the request body. Previously, this was sent in the request headers.
**v1 (Header)**
x-zitadel-orgid: 1234567890
**v2 (Request Body)**
{
"organization_id": "1234567890"
}
### [Instances](https://zitadel.com/docs/apis/migration_v1_to_v2#instances)
No major changes have been made to the organization requests.
### [Organizations](https://zitadel.com/docs/apis/migration_v1_to_v2#organizations)
No major changes have been made to the organization requests.
### [Users](https://zitadel.com/docs/apis/migration_v1_to_v2#users)
When migrating your user management from v1 to v2, the most significant updates involve user states and the initial onboarding process:
* **Unified User Creation Endpoint**:
* A significant simplification in v2 is the consolidation of user creation. There is now one primary endpoint for creating users, regardless of whether they are User (Human) or service accounts.
* You can use this single endpoint to provision both users (individuals interacting with your application) and service accounts (i.e. API clients), typically by specifying the user type in the request payload.
* **No More "Initial" State**:
* In v1, new users without a password or verified email were automatically assigned an initial state. This default assumption wasn't always ideal.
* In v2, this initial state has been removed. All newly created users are now active by default, regardless of their initial attributes.
* **New Onboarding Process**:
* To enable users to set up their accounts, you can now send them an invitation code. This allows them to securely add their authentication methods.
* **Flexible Email Verification**:
* v2 provides more control over email verification:
* You can choose at user creation whether an email verification code should be sent automatically.
* Alternatively, the API can return the verification code directly to you, empowering you to send a customized verification email.
[Users API v2 Documentation](https://zitadel.com/docs/reference/api/user)
### [Projects](https://zitadel.com/docs/apis/migration_v1_to_v2#projects)
We've simplified how you interact with projects by unifying projects and granted\_projects into a single resource. From a consumer's perspective, it no longer matters if you own a project or if it was granted to you by another organization; it's all just a project.
The main difference now is your level of permission. Your permissions determine whether you have administrative rights (like updating the project's details) or if you can only view the project and manage authorizations for your users.
This change significantly streamlines API calls. For example, where you previously had to make two separate requests to see all projects, you now make one.
**v1 (Separate Requests):**
- ListProjects
- ListGrantedProjects
**v2 (Single Request with Filter):**
- ListProjects (returns all projects you have access to)
You can now use filters within the single ListProjects request if you need to differentiate between project types, such as filtering by projects you own versus those that have been granted to you. Update your code to use this new unified ListProjects endpoint.
### [Applications](https://zitadel.com/docs/apis/migration_v1_to_v2#applications)
We have streamlined the creation and management of applications. In v1, each application type had its own unique endpoints. In v2, we have unified these into a single set of endpoints for all application types.
The biggest change is in how you create/update applications. Instead of calling a specific endpoint for each type (e.g., CreateOidcApp, CreateSamlApp), you will now use a single CreateApp endpoint.
To specify the type of application, you will include its specific settings object within the request body. For example, to create a OIDC app, you will provide an oidc object in the request. All properties that are common to every application, such as name, are now top-level fields in the request body, consistent across all types.
This approach simplifies client-side logic, as you no longer need to route requests to different endpoints.
**v1 (Multiple, Type-Specific Endpoints):**
- AddOIDCApp
- AddSAMLApp
- AddAPIApp
**v2 (Single Endpoint with Type-Specific Body):**
- CreateApplication
- ProjectID
- Name
- Type
- OIDC
- SAML
- API
Was this page helpful?
[Updates name of an existing instance\
\
Updates name of an existing instance: Deprecated: Use \[UpdateInstance\](/reference/api/system/zitadel.system.v1.SystemService.UpdateInstance) instead to update the name of the instance in context](https://zitadel.com/docs/reference/api/system/zitadel.system.v1.SystemService.UpdateInstance)
[zitadel/assets\
\
Learn how to upload and manage instance, organization, or user assets such as logos and avatars using ZITADEL's AssetsService API endpoints. Full reference and examples included.](https://zitadel.com/docs/apis/assets/assets)
### On this page
[The v1 Approach: Use-Case Based APIs](https://zitadel.com/docs/apis/migration_v1_to_v2#the-v-1-approach-use-case-based-ap-is)
[The v2 Approach: A Resource-Based API](https://zitadel.com/docs/apis/migration_v1_to_v2#the-v-2-approach-a-resource-based-api)
[Why the Change](https://zitadel.com/docs/apis/migration_v1_to_v2#why-the-change)
[Resource Migration](https://zitadel.com/docs/apis/migration_v1_to_v2#resource-migration)
[General Changes](https://zitadel.com/docs/apis/migration_v1_to_v2#general-changes)
[Sunsetting OpenAPI/REST Support in Favor of Connect RPC](https://zitadel.com/docs/apis/migration_v1_to_v2#sunsetting-open-api-rest-support-in-favor-of-connect-rpc)
[Contextual Information in the Request Body](https://zitadel.com/docs/apis/migration_v1_to_v2#contextual-information-in-the-request-body)
[Instances](https://zitadel.com/docs/apis/migration_v1_to_v2#instances)
[Organizations](https://zitadel.com/docs/apis/migration_v1_to_v2#organizations)
[Users](https://zitadel.com/docs/apis/migration_v1_to_v2#users)
[Projects](https://zitadel.com/docs/apis/migration_v1_to_v2#projects)
[Applications](https://zitadel.com/docs/apis/migration_v1_to_v2#applications)
---
# Data Processing Agreement | ZITADEL Docs
Legal Agreements
Data Processing Agreement
=========================
Last updated on May 8, 2025
This Data Protection Agreement and its annexes (“**DPA**”) are part of the [Framework Agreement](https://zitadel.com/docs/legal/terms-of-service)
between Zitadel, Inc. and it's affiliates ("**Zitadel**") and the Customer in respect of the provision of certain services, including any applicable statement of work, booking, purchase order (PO) or any agreed upon instructions (the "**Agreement**") and applies where, and to the extent that, Zitadel processes Personal Data as a Processor on behalf of the Customer under the Framework Agreement (each a “**Party**” and together the “**Parties**”).
All capitalized terms not defined in this DPA will have the meanings set forth in the Agreement. Any privacy or data protection related clauses or agreement previously entered into by Zitadel and the Customer, with regards to the subject matter of this DPA, will be superseded and replaced by this DPA. No one other than a Party to this DPA, their successors and permitted assignees will have any right to enforce any of its terms.
This DPA shall become legally binding upon Customer entering into the Agreement.
[Definitions](https://zitadel.com/docs/legal/data-processing-agreement#definitions)
------------------------------------------------------------------------------------
"**Applicable Data Protection Law**" means all worldwide data protection and privacy laws and regulations applicable to the Personal Data, including, where applicable, EU/UK Data Protection Law and US Data Protection Laws (in each case, as amended, adopted, or superseded from time to time).
“**Controller**,” “**collecting**,” “**processor**,” and “**processing**,” shall have the meanings given to them under Applicable Data Protection Law.
“**Business**,” “**service provider**,” “**contractor**,” “**selling**,” “**sharing**” and “**third party**” shall have the meanings given to them under applicable US Data Protection Laws.
"**Customer Data**" means information, data and other content, in any form or medium, that is submitted, posted or otherwise transmitted by or on behalf of the Customer through the Zitadel Cloud or Services. For the avoidance of doubt, Customer Data includes Customer Personal Data.
“**Customer Personal Data**” means, in any form or medium, all Personal Data that is processed by Zitadel or its sub-processors on behalf of Customer in connection with the Agreement.
“**EU/UK Data Protection Law**” means: (i) Regulation 2016/679 of the European Parliament and of the Council on the protection of natural persons with regard to the processing of Personal Data and on the free movement of such data, also known as the General Data Protection Regulation (“**GDPR**”); (ii) the GDPR as saved into United Kingdom law by virtue of section 3 of the United Kingdom’s European Union (Withdrawal) Act 2018 (“**UK GDPR**”); (iii) the EU e-Privacy Directive (Directive 2002/58/EC); (iv) the Swiss Federal Act on Data Protection of 2020 and its Ordinance (“**Swiss FADP**”) and (v) any and all applicable national data protection laws and regulatory requirements made under, pursuant to or that apply in conjunction with any of (i), (ii) or (iii); in each case as may be amended or superseded from time to time.
“**Personal Data**” shall have the meaning given to it, or to the terms “personally identifiable information” and “personal information” under applicable Data Protection Law, but shall include, at a minimum, any information related to an identified or identifiable natural person.
“**Restricted Transfer**” means: (i) where the GDPR applies, a transfer of Personal Data from the EEA to a country outside of the EEA which is not subject to an adequacy determination by the European Commission; and (ii) where UK-GDPR applies, a transfer of Personal Data from the United Kingdom to any other country which is not subject to adequacy regulations pursuant to Section 17A of the United Kingdom Data Protection Act 2018, in each case whether such transfer is direct or via onward transfer.
“**Security Incident**” means any unauthorized or unlawful breach of security leading to, or reasonably believed to have led to, the accidental or unlawful destruction, loss, or alteration of, or unauthorized disclosure or access to, Personal Data transmitted, stored or otherwise processed by Zitadel under or in connection with the Agreement.
“**Standard Contractual Clauses**” or “**SCCs**” means the contractual clauses annexed to the European Commission’s Implementing Decision 2021/914 of 4 June 2021 on standard contractual clauses for the transfer of personal data to third countries pursuant to Regulation (EU) 2016/679 of the European Parliament and of the Council.
“**sub-processor**” means any third-party processor engaged by Zitadel to process Customer Data (but shall not include Zitadel employees, contractors or consultants).
“**UK Addendum**” means the International Data Transfer Addendum (version B1.0) issued by the Information Commissioner’s Office under S119(A) of the UK Data Protection Act 2018, as updated or amended from time to time.
“**US Data Protection Laws**” means any relevant U.S. federal and state privacy laws (and any implementing regulations and amendment thereto) effective as of the date of this DPA and that applies to the processing of Customer Personal Data under the Agreement, which may include, depending on the circumstances and without limitation, (i) the California Consumer Privacy Act (Cal. Civ. Code §§ 1798.100 et seq.), as amended by the California Privacy Rights Act of 2020 along with its implementing regulations (“**CCPA**”), (ii) the Colorado Privacy Act (Colo. Rev. Stat. §§ 6-1-1301 et seq.) (CPA), (iii) Connecticut’s Data Privacy Act (CTDPA), (iv) the Utah Consumer Privacy Act (Utah Code Ann. §§ 13-61-101 et seq.) (UCPA) and (v) the Virginia Consumer Data Protection Act VA Code Ann. §§ 59.1-575 et seq. (VCDPA).
[Processing of Personal Data](https://zitadel.com/docs/legal/data-processing-agreement#processing-of-personal-data)
--------------------------------------------------------------------------------------------------------------------
This DPA applies where and only to the extent that Zitadel processes Customer Personal Data in connection with the provision of the Services under the Agreement involving the processing of Personal Data protected by Applicable Data Protection Law. This DPA reflects the commitment of both Parties to abide by Applicable Data Protection Law for the processing of Personal Data by Zitadel as a processor for the purpose of the Zitadel's provision of the Services and its execution of the Agreement.
This DPA will become effective on the date the Agreement enters into effect and will remain in force for the term of the Agreement, unless otherwise provided for in this DPA or unless individual provisions obviously result in obligations going beyond this. For the avoidance of doubt, the terms of the Framework Agreement will continue in full force and effect; however, to the extent any term in any Agreement regarding either Party’s obligations with respect to Customer Data is less restrictive than or is inconsistent with this DPA, the terms of this DPA shall supersede and control.
The Parties acknowledge that the following Customer Data will be processed as part of the Services:
| Type of personal data | Examples | Affected data subjects |
| --- | --- | --- |
| Basic data | * Names
* Email addresses
* User names | All users as uploaded by Customer. |
| Login details | * Randomly generated ID
* Passwords
* Public keys / certificates ("FIDO2", "U2F", "x509", ...)
* User names or identifiers of external login providers
* Phone numbers | All users as uploaded and feature use by Customer. |
| Profile data | * Profile pictures
* Gender
* Languages
* Nicknames or Display names
* Phone numbers
* Metadata | All users as uploaded by Customer |
| Communication data | * Emails
* Chats
* Call metadata
* Call recording and transcripts
* Form submissions | Customers and users who communicate with us directly (e.g. support, chat). |
| Payment data | * Billing address
* Payment information
* Customer number
* Support Customer history
* Credit rating information | Customers who use services that require payment. Credit rating information: Only customers who pay by invoice. |
| Analytics data | * Usage metrics
* User behavior
* User journeys (eg, Milestones)
* Telemetry data
* Client-side anonymized session replay | Customers who use our services. |
| Usage metadata | * User agent
* IP addresses
* Operating system
* Time and date
* URL
* Referrer URL
* Accepted Language | All users |
[Scope](https://zitadel.com/docs/legal/data-processing-agreement#scope)
------------------------------------------------------------------------
Under this Agreement, Zitadel shall process Customer Personal Data to perform its obligations under the Agreement and and strictly in accordance with the documented instructions of Customer (the “**Permitted Purpose**”), except where otherwise required by law(s) that are not incompatible with Applicable Data Protection Law.
The Parties acknowledge and agree that for the purposes of this DPA, the Customer is the controller and appoints Zitadel as a processor to process the Customer Personal Data. To the extent that the Parties are subject to the California Consumer Privacy Act (CCPA), the Customer is the business whereas Zitadel is a service provider to the Customer. Each Party shall comply with the obligations that apply to it under Applicable Data Protection Law.
Each Party shall comply with its own obligations under Applicable Data Protection Law in respect of any Customer Personal Data processed under the Agreement.
[Customer's Responsibilities](https://zitadel.com/docs/legal/data-processing-agreement#customers-responsibilities)
-------------------------------------------------------------------------------------------------------------------
The Customer’s instructions to Zitadel shall comply with Applicable Data Protection Law. The Customer will have sole responsibility for the accuracy, quality and legality of the Customer Data, the means by which the Customer acquired the Customer Data, and the Customer's permissions to process the Customer Data pursuant to this DPA.
As required under Applicable Data Protection Law, the Customer will provide all necessary notices to data subjects and secure the applicable lawful grounds for processing Data under the DPA, including where applicable, all necessary permissions and consents from them. To the extent required under Applicable Data Protection Law, the Customer will receive and document the appropriate consent from the data subject(s).
The Customer represents and warrants that (i) it complies with Applicable Data Protection Law as relevant to the lawful processing by Zitadel of Customer Personal Data for the purposes contemplated by this DPA and the Agreement; and (ii) to the knowledge of the Customer, the processing of Customer Personal Data by Zitadel in accordance with the Customer’s instructions will not cause Zitadel to be in breach of any Applicable Data Protection Law.
The Customer shall not disclose any special categories of Personal Data or sensitive personal information (as these terms are defined under Applicable Data Protection Law) to Zitadel for processing.
[Obligations of the processor](https://zitadel.com/docs/legal/data-processing-agreement#obligations-of-the-processor)
----------------------------------------------------------------------------------------------------------------------
### [Bound by the Customer's directions and instructions](https://zitadel.com/docs/legal/data-processing-agreement#bound-by-the-customers-directions-and-instructions)
Customer hereby instructs Zitadel to process Customer Data for the Permitted Purpose.
Zitadel processes Personal Data in accordance with its privacy policy (cf. [Privacy Policy](https://zitadel.com/docs/legal/policies/privacy-policy)
) and upon the documented directions of the Customer (which includes the Agreement). Subsequent instructions shall be given either in writing, whereby e-mail shall suffice, or orally with immediate written confirmation.
Zitadel shall promptly inform Customer if it becomes aware that such processing instructions infringe Applicable Data Protection Law (but without obligation to actively monitor compliance with Applicable Data Protection Law). In such case, Zitadel shall be entitled to suspend the processing until the infringing instruction is withdrawn or confirmed.
### [Confidentiality obligations](https://zitadel.com/docs/legal/data-processing-agreement#confidentiality-obligations)
Zitadel shall ensure that any person that it authorizes to process Customer Data (including Zitadel’s staff, agents and sub-processors) (an “Authorized Person”) shall be subject to a strict duty of confidentiality (whether a contractual duty or a statutory duty) and shall not permit any person to process the Customer Data that is not under such a duty of confidentiality. Zitadel shall ensure that all Authorized Persons process the Customer Data only as necessary for the Permitted Purpose.
### [Technical and organizational measures](https://zitadel.com/docs/legal/data-processing-agreement#technical-and-organizational-measures)
Zitadel shall implement appropriate technical and organizational measures to protect the Customer Data from a Security Incident, as described in Annex II to this DPA. Such measures shall comply with all Applicable Data Protection Law and shall further have regard to the state of the art, the costs of implementation and the nature, scope, context and purposes of processing as well as the risk of varying likelihood and severity for the rights and freedoms of natural persons. The Customer acknowledges that such measures are subject to technical progress and development and that Zitadel may update or modify such measures from time to time, provided that such updates and modifications do not degrade or diminish overall security of the Customer Data, or of the Services under the Agreement.
### [Involvement of subcontracted processors](https://zitadel.com/docs/legal/data-processing-agreement#involvement-of-subcontracted-processors)
Customer agrees that Zitadel may engage sub-processors to process Customer Data on Customer’s behalf. A current and complete [list of involved and approved sub-processors](https://zitadel.com/trust)
can be found on our [Trust Center](https://zitadel.com/trust)
(as may be updated from time to time in accordance with this DPA).
Zitadel will notify Customer by updating the list of sub-processors and, if Customer has subscribed to notices, via email. If, within five (5) calendar days after such notice, Customer notifies Zitadel in writing that Customer objects to Zitadel's appointment of a new sub-processor based on reasonable data protection concerns, the parties will discuss such concerns in good faith with a view to achieving a commercially reasonable resolution. If the parties are not able to mutually agree to a resolution of such concerns, Customer, as its sole and exclusive remedy, may terminate the Agreement for convenience with no refunds and Customer will remain liable to pay any committed fees in an order form, order, statement of work or other similar ordering document.
Zitadel shall inform the Customer if it adds or replaces any sub-processor at least fifteen (15) days prior to any such change (including details of the processing it performs or will perform). The Customer may object in writing to Zitadel’s engagement of a new sub-processor on reasonable grounds relating to the protection of Customer Personal Data by notifying Zitadel promptly in writing within fifteen (15) calendar days of receipt of Zitadel’s notice. In such case, the parties shall discuss Customer’s concerns in good faith with a view to achieving a commercially reasonable resolution. If such objection right is not exercised by Customer, silence shall be deemed to constitute an approval of the relevant sub-processor engagement.
Where Zitadel appoints a sub-processor, Zitadel shall: (i) enter into an agreement with each sub-processor containing data protection terms that provide at least the same level of protection for Customer Data as those contained in this DPA, to the extent applicable to the nature of the services provided by such sub-processor; and (ii) remain responsible to the Customer for Zitadel’s sub-processors’ failure to perform their obligations with respect to the processing of Customer Data.
Taking into account the safeguards set forth in this DPA, Customer Data may be processed outside of Switzerland or the EU/EAA, such as in the United States or any country in which Zitadel or is sub-processors operate. Our [list of involved and approved sub-processors](https://zitadel.com/trust)
provides additional details.
### [Assistance in responding to requests](https://zitadel.com/docs/legal/data-processing-agreement#assistance-in-responding-to-requests)
Zitadel shall provide all reasonable and timely assistance (which may include by appropriate technical and organizational measures) to the Customer to enable the Customer to respond to: (i) any request from a data subject to exercise any of their rights under Applicable Data Protection Law ("**Data Subject Request**"); and (ii) any other correspondence, enquiry or complaint received from a data subject, regulator or other third party in connection with the processing of Customer Personal Data.
In the event that any such request, correspondence, enquiry or complaint is made directly to Zitadel, Zitadel shall promptly inform the Customer providing full details of the same. Zitadel will not respond to a Data Subject Request, however the Customer acknowledges and agrees that Zitadel may at its discretion respond to confirm that such request relates to the Customer.
The Customer hereby acknowledges and agrees that the Services include features which will allow the Customer to manage Data Subject Requests directly through the Services without additional assistance from the Processor. If the Customer does not have the ability to address a Data Subject Request, Zitadel will, upon the Customer’s written request, provide reasonable assistance to facilitate the Customer’s response to such Data Subject Request to the extent such assistance is consistent with Applicable Data Protection Law; provided that the Customer will be responsible for paying for any reasonable costs incurred or fees charged by Zitadel for providing such assistance.
Zitadel, unless prohibited from doing so by applicable law, will promptly notify the Customer of any requests from a regulator, law enforcement authority or any other relevant and competent authority in relation to the Customer Personal Data that is being processed on behalf of the Customer, to the extent that the request may result in the disclosure of Customer Personal Data to such regulator, law enforcement authority or any other relevant and competent authority.
### [Cooperation and support for the Customer](https://zitadel.com/docs/legal/data-processing-agreement#cooperation-and-support-for-the-customer)
Zitadel shall provide the Customer with all such reasonable and timely assistance as Customer may require in order to enable it to conduct a data protection impact assessment (or equivalent document) where required by Applicable Data Protection Law, including, if necessary, to assist Customer to consult with its relevant data protection or other regulatory authority.
### [Security incidents](https://zitadel.com/docs/legal/data-processing-agreement#security-incidents)
Upon becoming aware of a Security Incident, Zitadel shall inform Customer without undue delay and provide all such timely information and cooperation as Customer may require for the Customer to fulfil its data breach or cybersecurity incident reporting obligations under (and in accordance with the timescales required by) Applicable Data Protection Law. Customer shall further take all such measures and actions as are reasonable and necessary to investigate, contain, and remediate or mitigate the effects of the Security Incident, to the extent that the remediation is within Zitadel's control, and shall keep Customer informed of all material developments in connection with the Security Incident.
Notwithstanding anything to the contrary, Zitadel's notification of or response to a Security Incident under this section will not be construed as an acknowledgment by Zitadel of any fault or liability with respect to such Security Incident.
### [Deletion or destruction after termination](https://zitadel.com/docs/legal/data-processing-agreement#deletion-or-destruction-after-termination)
Upon termination or expiry of the Agreement, Zitadel shall (at the Customer’s election) destroy or return to the Customer all Customer Data (including all copies of the Customer Data) in its possession or control (including any Customer Data subcontracted to a third party for processing). This requirement shall not apply to the extent that Zitadel is required by any applicable law to retain some or all Customer Data, in which case Zitadel shall isolate and protect the Customer Data from any further processing except to the extent required by such law until deletion is possible.
### [Customer's information and audit rights](https://zitadel.com/docs/legal/data-processing-agreement#customers-information-and-audit-rights)
To the extent required under Applicable Data Protection Law and on written request from the Customer, Zitadel shall provide written responses (which may include audit report summaries/extracts) to all reasonable requests for information made by the Customer related to its processing of Customer Personal Data as necessary to confirm Zitadel's compliance with this DPA. The Customer shall not exercise this right more than once in any twelve (12)-month rolling period, except (i) if and when required by instruction of a competent data protection or other regulatory authority; or (ii) if Zitadel has experienced a Security Incident where Customer was directly impacted.
Nothing in this section shall be construed to require Zitadel to document or provide: (i) trade secrets or any proprietary information; (ii) any information that would violate Zitadel’s confidentiality obligations, contractual obligations, or applicable law; or (iii) any information, the disclosure of which could threaten, compromise, or otherwise put at risk the security, confidentiality, or integrity of Zitadel’s infrastructure, networks, systems, algorithms or data.
### [Service Optimization](https://zitadel.com/docs/legal/data-processing-agreement#service-optimization)
Where permitted by Applicable Data Protection Law, Zitadel may process Customer Data: (i) for its internal uses to build or improve the quality of its services; (ii) to detect Security Incidents; and (iii) to protect against fraudulent or illegal activity.
Zitadel may: (i) compile aggregated and/or de-identified information in connection with the provision of the Services, provided that such information cannot reasonably be used to identify Customer or any data subject to whom Customer Personal Data relates (“Aggregated and/or De-Identified Data”); and (ii) use such Aggregated and/or De-Identified Data for its lawful business purposes in accordance with Applicable Data Protection Law.
### [Data Transfers](https://zitadel.com/docs/legal/data-processing-agreement#data-transfers)
Where either Party intends to transfer Personal Data cross-border and Applicable Data Protection Law requires certain measures to be implemented prior to such transfer, each Party agrees to implement such measures to ensure compliance with Applicable Data Protection Law.
To the extent that the transfer of Personal Data from Customer to Zitadel involves a transfer of Personal Data outside the European Economic Area (EEA), Switzerland, or the United Kingdom to a jurisdiction which is not subject to an adequacy determination by the European Commission, United Kingdom or Swiss authorities (as applicable) that covers such transfer, then the SCCs are hereby incorporated by reference and form an integral part of the DPA.
#### [EEA Transfers](https://zitadel.com/docs/legal/data-processing-agreement#eea-transfers)
To the extent that Customer Personal Data is subject to the GDPR, and the transfer would be a Restricted Transfer, the SCCs apply as follows:
1. the Customer is the ‘data exporter’ and Zitadel is the ‘data importer’;
2. the Module Two terms (Transfer controller to processor) apply;
3. in Clause 7, the optional docking clause does not apply;
4. in Clause 9, Option 2 (General Authorization) applies and the time period for prior notice of sub-processor changes is set out in this DPA;
5. in Clause 11, the optional language does not apply;
6. in Clause 17, Option 1 applies, and the SCCs are governed by German law;
7. in Clause 18(b), disputes will be resolved before the courts of Hamburg in Germany;
8. in Annex I, the details of the parties and the transfer are set out in the Agreement;
9. in Clause 13(a) and Annex I, the Hamburg data protection authority will act as competent supervisory authority;
10. in Annex II, the description of the technical and organizational security measures is set out in Annex 2 of this DPA or, if not set out therein, the applicable statement of work; and
11. in Annex III, the list of sub-processors is set out at the address [https://zitadel.com/trust](https://zitadel.com/trust)
or, if not set out therein, applicable statement of work.
#### [Swiss Transfers](https://zitadel.com/docs/legal/data-processing-agreement#swiss-transfers)
To the extent that Customer Personal Data is subject to Swiss law, and the transfer would be a Restricted Transfer, the SCCs apply as set out above with the following modifications:
1. references to ‘Regulation (EU) 2016/679’ are interpreted as references to the Swiss FADP or any successor thereof;
2. references to specific articles of ‘Regulation (EU) 2016/679’ are replaced with the equivalent article or section of the Swiss FADP,
3. references to ‘EU’, ‘Union’ and ‘Member State’ are replaced with ‘Switzerland’,
4. Clause 13(a) and Part C of Annex 2 is not used and the ‘competent supervisory authority’ is the Swiss Federal Data Protection Information Commissioner (“**FDPIC**”) or, if the transfer is subject to both the Swiss FADP and the GDPR, the FDPIC (insofar as the transfer is governed by the Swiss FADP) or the DPC (insofar as the transfer is governed by the GDPR),
5. references to the ‘competent supervisory authority’ and ‘competent courts’ are replaced with the FDPIC and ‘competent Swiss courts’,
6. in Clause 17, the SCCs are governed by the laws of Switzerland,
7. in Clause 18(b), disputes will be resolved before the competent Swiss courts, and
8. the SCCs also protect the data of legal entities until entry into force of the revised Swiss FADP.
#### [UK Transfers](https://zitadel.com/docs/legal/data-processing-agreement#uk-transfers)
To the extent that Customer Personal Data is subject to Applicable Data Protection Law of the United Kingdom, and the transfer would be a Restricted Transfer, the SCCs as set out above shall apply as amended by Part 2 of the UK Addendum, and Part 1 of the UK Addendum is deemed completed as follows:
1. in Table 1, the details of the parties are set out in the Agreement or, if not set out therein, the applicable statement of work;
2. in Table 2, the selected modules and clauses are set out in Section 6.3 of this DPA;
3. in Table 3, the appendix information is set out in the annexes to this DPA or, if not set out therein, the applicable statement of work; and
4. in Table 4, the ‘Exporter’ is selected.
#### [Alternative Transfer Mechanism](https://zitadel.com/docs/legal/data-processing-agreement#alternative-transfer-mechanism)
In the event that a court of competent jurisdiction or supervisory authority orders (for whatever reason) that the measures described in this DPA cannot be relied on to lawfully transfer Customer Personal Data, or Zitadel adopts an alternative data transfer mechanism to the mechanisms described in this DPA, including any new version of or successor to the standard contractual clauses (“Alternative Transfer Mechanism”), the Customer agrees to fully co-operate with Zitadel to agree an amendment to this DPA and/or execute such other documents and take such other actions as may be necessary to remedy such non-compliance or give legal effect to such Alternative Transfer Mechanism.
### [Additional Provisions under US Data Protection Laws](https://zitadel.com/docs/legal/data-processing-agreement#additional-provisions-under-us-data-protection-laws)
The Parties agree that all Customer Personal Data that is subject to US Data Protection Laws (including the CCPA) is disclosed to Zitadel by the Customer for the Permitted Purpose and its use or sharing by the Customer with Zitadel is necessary to perform such Permitted Purpose.
Zitadel agrees that it will not:
1. sell or share any Customer Personal Data to a third party for any purpose other than than for the Permitted Purpose;
2. retain, use, or disclose any Customer Personal Data (i) for any purpose other than for the Permitted Purpose, including for any commercial purpose, or (ii) outside of the direct business relationship between the Parties, except as necessary to perform the Permitted Purpose or as otherwise permitted by US Data Protection Laws; or
3. combine Customer Personal Data received from or on behalf of Customer with Personal Data received from or on behalf of any third party or collected from Zitadel’s own interaction with individuals or data subjects, except to perform a Permitted Purpose in accordance with the CCPA, the Agreement and this DPA.
The Parties acknowledge that the Customer Personal Data that Customer discloses to Zitadel is provided only for the limited and specified purposes set forth as the Permitted Purpose in the Agreement and this DPA.
Zitadel shall provide the same level of protection to Customer Personal Data as required by the CCPA and will: (i) assist the Customer in responding to any request from a data subject to exercise rights under US Data Protection Laws; and (ii) immediately notify the Customer if it is not able to meet the requirements under the CCPA.
The Customer may take such reasonable and appropriate steps as may be necessary (a) to ensure that the Customer Personal Data collected is used in a manner consistent with the business’s obligations under the CCPA; and (b) to stop and remediate any unauthorized use of Customer Personal Data, and (b) to ensure that Customer Personal Data is used in a manner consistent with the CCPA.
### [Miscellaneous](https://zitadel.com/docs/legal/data-processing-agreement#miscellaneous)
This DPA shall be governed by and construed in accordance with the governing law and jurisdiction provisions set out in the Agreement, unless required otherwise by Applicable Data Protection Law.
Any liability owed by one party to the other under this DPA shall be subject to the limitations of liability set forth in the Agreement.
This DPA shall terminate upon the earlier of (i) the termination or expiry of all Agreement under which Customer Data may be processed, or (ii) the written agreement of the Parties.
Any notices shall be delivered to a Party in accordance with the notice provisions of the Agreement, unless otherwise specified hereunder.
[Annex 1: Description of Processing Activities / Transfer](https://zitadel.com/docs/legal/data-processing-agreement#annex-1-description-of-processing-activities-transfer)
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### [List of Parties](https://zitadel.com/docs/legal/data-processing-agreement#list-of-parties)
| Data Exporter | Data Importer |
| --- | --- |
| Name: The Party identified as the Customer in the Agreement. | Name: The Party identified as Zitadel in the Agreement. |
| Address: As identified in the Agreement. | Address: As identified in the Agreement. |
| Contact Person's Name, position and contact details: As identified in the Agreement. | Contact Person's Name, position and contact details: As identified in the Agreement. |
| Activities relevant to the transfer: See below | Activities relevant to the transfer: See below |
| Role: Controller | Role: Processor |
### [Description of processing / transfer](https://zitadel.com/docs/legal/data-processing-agreement#description-of-processing-transfer)
| | Description |
| --- | --- |
| **Categories of data subjects:** | As described in the section "Processing of Personal Data" of the DPA |
| **Categories of personal data:** | As described in the section "Processing of Personal Data" of the DPA |
| **Sensitive data:** | None. |
| **If sensitive data, the applied restrictions or safeguards** | N/A |
| **Frequency of the transfer:** | Continuous |
| **Nature and subject matter of processing:** | The Services described in the Agreement. |
| **Purpose(s) of the data transfer and further processing:** | As set forth in the Agreement. |
| **Retention period (or, if not possible to determine, the criteria used to determine that period):** | The personal data may be retained until termination or expiry of the DPA. |
### [Competent supervisory authority](https://zitadel.com/docs/legal/data-processing-agreement#competent-supervisory-authority)
The competent supervisory authority in connection with Customer Personal Data protected by the GDPR, is the Hamburg data protection authority. If this is not possible, then as otherwise agreed by the parties consistent with the conditions set forth in Clause 13.
In connection with Customer Personal Data that is protected by UK-GDPR, the competent supervisory authority is the Information Commissioners Office (the "ICO").
[Annex 2: Technical and organizational measures](https://zitadel.com/docs/legal/data-processing-agreement#annex-2-technical-and-organizational-measures)
---------------------------------------------------------------------------------------------------------------------------------------------------------
Zitadel has implemented an information security program, that is designed to protect the confidentiality, integrity and availability of Customer Data. Zitadel's information security program includes the following organizational and technical security measures to ensure a level of protection of the Personal Data processed that is appropriate to the risk:
### [Pseudonymization / Encryption](https://zitadel.com/docs/legal/data-processing-agreement#pseudonymization-encryption)
The following measures for pseudonymization and encryption exist:
1. All communication is encrypted with TLS >1.2 with PFS
2. Critical data is exclusively stored in encrypted form
3. Storage media that store customer data are always encrypted
4. Passwords are irreversibly stored with a hash function
5. Data for web analytics are pseudonymized and do not contain any personal data
### [Ensuring certain properties of the systems and services](https://zitadel.com/docs/legal/data-processing-agreement#ensuring-certain-properties-of-the-systems-and-services)
#### [Confidentiality](https://zitadel.com/docs/legal/data-processing-agreement#confidentiality)
The following confidentiality measures exist:
1. Information security policies
2. Authentication policies
3. Vendor management policies
4. Technical measures in this annex
#### [Integrity](https://zitadel.com/docs/legal/data-processing-agreement#integrity)
The following integrity measures exist:
1. Code and container images are automatically checked for vulnerabilities
2. An automated system is used to keep dependencies up to date
3. Secrets are automatically rotated whenever possible and are short-lived (for example, signing keys)
4. Changes to code or infrastructure require mandatory review by at least one other employee
#### [Availability](https://zitadel.com/docs/legal/data-processing-agreement#availability)
The following measures of availability exist:
1. Operation of the systems in combination with a CDN/DDoS mitigation service
2. High availability operation
3. Geo-redundant operation over at least two data centers
#### [Load capacity](https://zitadel.com/docs/legal/data-processing-agreement#load-capacity)
The following measures of availability exist:
1. Automatic scaling of resources
2. Monitoring, logging, tracing and alerting
#### [Restoring availability and access](https://zitadel.com/docs/legal/data-processing-agreement#restoring-availability-and-access)
The following measures exist to restore availability and access:
1. Implementation of a backup concept
2. Emergency plan
3. Testing of the emergency plan
#### [Regular review, assessment and evaluation of effectiveness](https://zitadel.com/docs/legal/data-processing-agreement#regular-review-assessment-and-evaluation-of-effectiveness)
The following measures exist for regular review, assessment and evaluation of effectiveness:
1. At least annual audit and evaluation of processes within the framework of an information security management system
2. Responsible Disclosure and Bug Bounty policies
3. External audit of system security ("penetration testing")
Was this page helpful?
[Terms of Service Agreement\
\
Framework agreement and terms of service for ZITADEL's websites and identity management services.](https://zitadel.com/docs/legal/terms-of-service)
[Third Party Sub-Processors\
\
List of third-party sub-processors and services used by ZITADEL to provide its identity and authentication services.](https://zitadel.com/docs/legal/subprocessors)
### On this page
[Definitions](https://zitadel.com/docs/legal/data-processing-agreement#definitions)
[Processing of Personal Data](https://zitadel.com/docs/legal/data-processing-agreement#processing-of-personal-data)
[Scope](https://zitadel.com/docs/legal/data-processing-agreement#scope)
[Customer's Responsibilities](https://zitadel.com/docs/legal/data-processing-agreement#customers-responsibilities)
[Obligations of the processor](https://zitadel.com/docs/legal/data-processing-agreement#obligations-of-the-processor)
[Bound by the Customer's directions and instructions](https://zitadel.com/docs/legal/data-processing-agreement#bound-by-the-customers-directions-and-instructions)
[Confidentiality obligations](https://zitadel.com/docs/legal/data-processing-agreement#confidentiality-obligations)
[Technical and organizational measures](https://zitadel.com/docs/legal/data-processing-agreement#technical-and-organizational-measures)
[Involvement of subcontracted processors](https://zitadel.com/docs/legal/data-processing-agreement#involvement-of-subcontracted-processors)
[Assistance in responding to requests](https://zitadel.com/docs/legal/data-processing-agreement#assistance-in-responding-to-requests)
[Cooperation and support for the Customer](https://zitadel.com/docs/legal/data-processing-agreement#cooperation-and-support-for-the-customer)
[Security incidents](https://zitadel.com/docs/legal/data-processing-agreement#security-incidents)
[Deletion or destruction after termination](https://zitadel.com/docs/legal/data-processing-agreement#deletion-or-destruction-after-termination)
[Customer's information and audit rights](https://zitadel.com/docs/legal/data-processing-agreement#customers-information-and-audit-rights)
[Service Optimization](https://zitadel.com/docs/legal/data-processing-agreement#service-optimization)
[Data Transfers](https://zitadel.com/docs/legal/data-processing-agreement#data-transfers)
[EEA Transfers](https://zitadel.com/docs/legal/data-processing-agreement#eea-transfers)
[Swiss Transfers](https://zitadel.com/docs/legal/data-processing-agreement#swiss-transfers)
[UK Transfers](https://zitadel.com/docs/legal/data-processing-agreement#uk-transfers)
[Alternative Transfer Mechanism](https://zitadel.com/docs/legal/data-processing-agreement#alternative-transfer-mechanism)
[Additional Provisions under US Data Protection Laws](https://zitadel.com/docs/legal/data-processing-agreement#additional-provisions-under-us-data-protection-laws)
[Miscellaneous](https://zitadel.com/docs/legal/data-processing-agreement#miscellaneous)
[Annex 1: Description of Processing Activities / Transfer](https://zitadel.com/docs/legal/data-processing-agreement#annex-1-description-of-processing-activities-transfer)
[List of Parties](https://zitadel.com/docs/legal/data-processing-agreement#list-of-parties)
[Description of processing / transfer](https://zitadel.com/docs/legal/data-processing-agreement#description-of-processing-transfer)
[Competent supervisory authority](https://zitadel.com/docs/legal/data-processing-agreement#competent-supervisory-authority)
[Annex 2: Technical and organizational measures](https://zitadel.com/docs/legal/data-processing-agreement#annex-2-technical-and-organizational-measures)
[Pseudonymization / Encryption](https://zitadel.com/docs/legal/data-processing-agreement#pseudonymization-encryption)
[Ensuring certain properties of the systems and services](https://zitadel.com/docs/legal/data-processing-agreement#ensuring-certain-properties-of-the-systems-and-services)
[Confidentiality](https://zitadel.com/docs/legal/data-processing-agreement#confidentiality)
[Integrity](https://zitadel.com/docs/legal/data-processing-agreement#integrity)
[Availability](https://zitadel.com/docs/legal/data-processing-agreement#availability)
[Load capacity](https://zitadel.com/docs/legal/data-processing-agreement#load-capacity)
[Restoring availability and access](https://zitadel.com/docs/legal/data-processing-agreement#restoring-availability-and-access)
[Regular review, assessment and evaluation of effectiveness](https://zitadel.com/docs/legal/data-processing-agreement#regular-review-assessment-and-evaluation-of-effectiveness)
---
# ZITADEL - Identity Infrastructure, Simplified
OIDC Playground
===============
The OIDC Playground is for testing OpenID Authentication Requests, giving you more insight how OpenID Connect works and how you can customize ZITADEL behavior with different parameters.
An OpenID Connect (OIDC) [authentication request](https://openid.net/specs/openid-connect-core-1_0.html)
is an OAuth 2.0 Authorization Request using additional parameters and scopes to request that the end-user be authenticated by ZITADEL.
Loading OIDC Playground...
Why this OIDC playground?
-------------------------
Currently ZITADEL requires Users (Human) to authenticate trough the hosted login page. Your application should initiate a login by issuing an authentication request and redirecting the user to the login page. You can customize the behavior of ZITADEL by providing additional parameters and scopes in the request.
This playground should help you to initially craft an authentication request and to explore the behavior of ZITADEL in more depth.
Request parameters explained
----------------------------
Not all request parameters are available in the playground. Please refer to the full documentation of the [authorization endpoint](https://zitadel.com/apis/openidoauth/endpoints#authorization_endpoint)
.
### Your Domain
The Instance Domain to your ZITADEL instance. Use the base-path, the playground will add the required path to the request.
### Required Parameters
Client ID is the resource id of an application. It's the application where you want your users to login. You can find the client ID in the Console. When using organization grants, use the client ID from the origin organization.
Redirect URI be one of the pre-configured redirect uris for your application. You must add the redirect URI for your application, else you will receive an error.
Response Type defines whether a `code`, `id_token token` or just `id_token` will be returned. Most use cases will need code.
More in the [documentation](https://zitadel.com/apis/openidoauth/endpoints#required-request-parameters)
about required Parameters.
### Authentication methods
Depending on the authentication and authorization flow of your application you might need to append some information to the authentication request.
Authentication method "(none) PKCE" is recommended for most application types. The playground appends automatically a code challenge for PKCE flows.
You need to append a "Code Challenge" by providing a random Code Verifier that is being hashed and encoded in the request to the token endpoint, please see our [guide](https://zitadel.com/guides/integrate/login/oidc/login-users#token-request)
for more details.
More in the [documentation](https://zitadel.com/apis/openidoauth/authn-methods)
about authentication methods.
### Additional Parameters
Prompt defines if and how the user should be prompted on login. For example:
* `select_account`: user is prompted to select one of the existing sessions or create a new one
* `create`: present the register form
* `login`: requires the user to re-authenticate
* `none`: user must be authenticated without interaction, an error is returned otherwise; use for silent-refresh
Login hint must be a valid logon name of a user. You can skip the account picker by providing the Login hint.
There are many more additional parameters. Please refer to the [documentation](https://zitadel.com/apis/openidoauth/endpoints#additional-parameters)
about additional parameters.
Standard Scopes
---------------
Used to request additional information from ZITADEL. These scopes are defined in the OpenID Connect specification. The `openid` scope is mandatory.
Not all scopes are available in the playground. Please refer to the full [documentation](https://zitadel.com/apis/openidoauth/scopes)
for the exhaustive list of available standard and reserved scopes.
Reserved Scopes
---------------
You can request additional information that is specific to ZITADEL or customize the behavior of ZITADEL by including reserved scopes. Please refer to the [documentation](https://zitadel.com/apis/openidoauth/scopes#reserved-scopes)
for a full list of available reserved scopes.
### Organization policies and branding
Enforce an organization's policies and branding as well as membership of the user by passing the scope `urn:zitadel:iam:org:id:{id}` with the required Organization ID.
Please refer to the full [guide on branding](https://zitadel.com/guides/manage/customize/branding)
.
### Get user metadata
Pass the scope `urn:zitadel:iam:user:metadata` to request a user's metadata. Please refer to the full [guide on user-metadata](https://zitadel.com/guides/manage/customize/user-metadata)
for further details.
### Access core apis
Calling the [core API](https://zitadel.com/apis/introduction)
with the authenticated user, requires that the projectID of ZITADEL is included in the audience claim.
This can be achieved by adding the scope `urn:zitadel:iam:org:project:id:zitadel:aud` to your applications authorization request.
How to use ZITADEL in your project
----------------------------------
Please refer to our [guide](https://zitadel.com/guides/integrate/login/oidc/login-users)
on how to login users.
OpenID Connect certified libraries should allow you to customize the parameters and define scopes for the authorization request. You can also continue by using one of our [example applications](https://zitadel.com/docs/sdk-examples/introduction)
.
---
# Configure ZITADEL | ZITADEL Docs
Configure ZITADEL
=================
Detailed configuration options for ZITADEL.
* [Configuration Guide](https://zitadel.com/docs/self-hosting/manage/configure/configure)
Was this page helpful?
---