From 27cd1d85182a34a808db6bf9b6afd520b0814e8c Mon Sep 17 00:00:00 2001 From: Livio Spring Date: Fri, 4 Jul 2025 13:00:24 -0400 Subject: [PATCH] docs(api): add new beta services to api reference (#10018) # Which Problems Are Solved The unreleased new resource apis have been removed from the docs: https://github.com/zitadel/zitadel/pull/10015 # How the Problems Are Solved Add them to the docs sidenav again, since they're now released. # Additional Changes none # Additional Context none --------- Co-authored-by: Fabienne Co-authored-by: Marco Ardizzone --- docs/docs/apis/migration_v1_to_v2.mdx | 173 ++++++++++ docs/sidebars.js | 444 +++++++++++++------------- 2 files changed, 396 insertions(+), 221 deletions(-) create mode 100644 docs/docs/apis/migration_v1_to_v2.mdx diff --git a/docs/docs/apis/migration_v1_to_v2.mdx b/docs/docs/apis/migration_v1_to_v2.mdx new file mode 100644 index 0000000000..6258b99fd9 --- /dev/null +++ b/docs/docs/apis/migration_v1_to_v2.mdx @@ -0,0 +1,173 @@ +--- +title: Migrate from v1 APIs to v2 APIs +--- + +This guide gives you an overview for migrating from our v1 API to the new and improved v2 API. +This upgrade introduces some significant architectural changes designed to make your development experience smoother, more intuitive, and efficient. + +## The v1 Approach: Use-Case Based APIs +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 +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 +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 + +This section details the migrated resources, including any breaking changes and other important considerations for your transition from v1 to v2. + +### General Changes + +#### Sunsetting OpenAPI/REST Support in Favor of Connect RPC +While our v1 API already offered gRPC, it also provided a parallel REST/OpenAPI interface for clients 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 bi-directional streaming. +- Connect RPC: For making CRUD-like (Create, Read, Update, Delete) calls over HTTP. This is the recommended path for most clients 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 clients 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 + +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 + +No major changes have been made to the organization requests. + +### Organizations + +No major changes have been made to the organization requests. + +### 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 human or machine users. + - You can use this single endpoint to provision both human users (individuals interacting with your application) and machine users (e.g., service accounts, 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](/docs/apis/resources/user_service_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 + +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 configuration object within the request body. +For example, to create a OIDC app, you will provide a 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 +``` \ No newline at end of file diff --git a/docs/sidebars.js b/docs/sidebars.js index 94978b8150..bc75f9ed87 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -664,6 +664,228 @@ module.exports = { id: "apis/apis/index", }, items: [ + + { + type: "category", + label: "V2", + collapsed: false, + link: { + type: "doc", + id: "apis/v2", + }, + items: [ + { + type: "category", + label: "User", + link: { + type: "generated-index", + title: "User Service API", + slug: "/apis/resources/user_service_v2", + description: + "This API is intended to manage users in a ZITADEL instance.\n", + }, + items: sidebar_api_user_service_v2, + }, + { + type: "category", + label: "Session", + link: { + type: "generated-index", + title: "Session Service API", + slug: "/apis/resources/session_service_v2", + description: + "This API is intended to manage sessions in a ZITADEL instance.\n", + }, + items: sidebar_api_session_service_v2, + }, + { + type: "category", + label: "OIDC", + link: { + type: "generated-index", + title: "OIDC Service API", + slug: "/apis/resources/oidc_service_v2", + description: + "Get OIDC Auth Request details and create callback URLs.\n", + }, + items: sidebar_api_oidc_service_v2, + }, + { + type: "category", + label: "Settings", + link: { + type: "generated-index", + title: "Settings Service API", + slug: "/apis/resources/settings_service_v2", + description: + "This API is intended to manage settings in a ZITADEL instance.\n", + }, + items: sidebar_api_settings_service_v2, + }, + { + type: "category", + label: "Feature", + link: { + type: "generated-index", + title: "Feature Service API", + slug: "/apis/resources/feature_service_v2", + description: + 'This API is intended to manage features for ZITADEL. Feature settings that are available on multiple "levels", such as instance and organization. The higher level instance acts as a default for the lower level. When a feature is set on multiple levels, the lower level takes precedence. Features can be experimental where ZITADEL will assume a sane default, such as disabled. When over time confidence in such a feature grows, ZITADEL can default to enabling the feature. As a final step we might choose to always enable a feature and remove the setting from this API, reserving the proto field number. Such removal is not considered a breaking change. Setting a removed field will effectively result in a no-op.\n', + }, + items: sidebar_api_feature_service_v2, + }, + { + type: "category", + label: "Organization", + link: { + type: "generated-index", + title: "Organization Service API", + slug: "/apis/resources/org_service/v2", + description: + "This API is intended to manage organizations for ZITADEL. \n", + }, + items: sidebar_api_org_service_v2, + }, + { + type: "category", + label: "Organization (Beta)", + link: { + type: "generated-index", + title: "Organization Service beta API", + slug: "/apis/resources/org_service/v2beta", + description: + "This API is intended to manage organizations for ZITADEL. \n", + }, + items: sidebar_api_org_service_v2beta, + }, + { + type: "category", + label: "Identity Provider", + link: { + type: "generated-index", + title: "Identity Provider Service API", + slug: "/apis/resources/idp_service_v2", + description: + "This API is intended to manage identity providers (IdPs) for ZITADEL.\n", + }, + items: sidebar_api_idp_service_v2, + }, + { + type: "category", + label: "Web Key", + link: { + type: "generated-index", + title: "Web Key Service API", + slug: "/apis/resources/webkey_service_v2", + description: + "This API is intended to manage web keys for a ZITADEL instance, used to sign and validate OIDC tokens.\n" + + "\n"+ + "The public key endpoint (outside of this service) is used to retrieve the public keys of the active and inactive keys.\n", + }, + items: sidebar_api_webkey_service_v2 + }, + { + type: "category", + label: "Action (Beta)", + link: { + type: "generated-index", + title: "Action Service API (Beta)", + slug: "/apis/resources/action_service_v2", + description: + "This API is intended to manage custom executions and targets (previously known as actions) in a ZITADEL instance.\n" + + "\n" + + "This service is in beta state. It can AND will continue breaking until a stable version is released.\n"+ + "\n" + + "The version 2 of actions provide much more options to customize ZITADELs behaviour than previous action versions.\n" + + "Also, v2 actions are available instance-wide, whereas previous actions had to be managed for each organization individually\n" + + "ZITADEL doesn't restrict the implementation languages, tooling and runtime for v2 action executions anymore.\n" + + "Instead, it calls external endpoints which are implemented and maintained by action v2 users.\n"+ + "\n" + + "Please make sure to enable the `actions` feature flag on your instance to use this service and that you're running Zitadel V3.", + }, + items: sidebar_api_actions_v2, + }, + { + type: "category", + label: "Instance (Beta)", + link: { + type: "generated-index", + title: "Instance Service API (Beta)", + slug: "/apis/resources/instance_service_v2", + description: + "This API is intended to manage instances, custom domains and trusted domains in ZITADEL.\n" + + "\n" + + "This service is in beta state. It can AND will continue breaking until a stable version is released.\n"+ + "\n" + + "This v2 of the API provides the same functionalities as the v1, but organised on a per resource basis.\n" + + "The whole functionality related to domains (custom and trusted) has been moved under this instance API." + , + }, + items: sidebar_api_instance_service_v2, + }, + { + type: "category", + label: "Project (Beta)", + link: { + type: "generated-index", + title: "Project Service API (Beta)", + slug: "/apis/resources/project_service_v2", + description: + "This API is intended to manage projects and subresources for ZITADEL. \n" + + "\n" + + "This service is in beta state. It can AND will continue breaking until a stable version is released.", + }, + items: sidebar_api_project_service_v2, + }, + { + type: "category", + label: "App (Beta)", + link: { + type: "generated-index", + title: "Application Service API (Beta)", + slug: "/apis/resources/application_service_v2", + description: + "This API lets you manage Zitadel applications (API, SAML, OIDC).\n"+ + "\n"+ + "The API offers generic endpoints that work for all app types (API, SAML, OIDC), "+ + "\n"+ + "This API is in beta state. It can AND will continue breaking until a stable version is released.\n" + }, + items: sidebar_api_app_v2, + }, + { + type: "category", + label: "Authorizations (Beta)", + link: { + type: "generated-index", + title: "Authorization Service API (Beta)", + slug: "/apis/resources/authorization_service_v2", + description: + "AuthorizationService provides methods to manage authorizations for users within your projects and applications.\n" + + "\n" + + "For managing permissions and roles for ZITADEL internal resources, like organizations, projects,\n" + + "users, etc., please use the InternalPermissionService."+ + "\n"+ + "This API is in beta state. It can AND will continue breaking until a stable version is released.\n" + }, + items: sidebar_api_authorization_service_v2, + }, + { + type: "category", + label: "Permissions (Beta)", + link: { + type: "generated-index", + title: "Permission Service API (Beta)", + slug: "/apis/resources/permission_service_v2", + description: + "This API is intended to manage internal permissions in ZITADEL.\n" + + "\n"+ + "This API is in beta state. It can AND will continue breaking until a stable version is released.\n" + }, + items: sidebar_api_permission_service_v2, + }, + ], + }, { type: "category", label: "V1", @@ -726,227 +948,7 @@ module.exports = { }, items: sidebar_api_system, }, - ], - }, - { - type: "category", - label: "V2", - collapsed: false, - link: { - type: "doc", - id: "apis/v2", - }, - items: [ - { - type: "category", - label: "User", - link: { - type: "generated-index", - title: "User Service API", - slug: "/apis/resources/user_service_v2", - description: - "This API is intended to manage users in a ZITADEL instance.\n", - }, - items: sidebar_api_user_service_v2, - }, - { - type: "category", - label: "Session", - link: { - type: "generated-index", - title: "Session Service API", - slug: "/apis/resources/session_service_v2", - description: - "This API is intended to manage sessions in a ZITADEL instance.\n", - }, - items: sidebar_api_session_service_v2, - }, - { - type: "category", - label: "OIDC", - link: { - type: "generated-index", - title: "OIDC Service API", - slug: "/apis/resources/oidc_service_v2", - description: - "Get OIDC Auth Request details and create callback URLs.\n", - }, - items: sidebar_api_oidc_service_v2, - }, - { - type: "category", - label: "Settings", - link: { - type: "generated-index", - title: "Settings Service API", - slug: "/apis/resources/settings_service_v2", - description: - "This API is intended to manage settings in a ZITADEL instance.\n", - }, - items: sidebar_api_settings_service_v2, - }, - { - type: "category", - label: "Feature", - link: { - type: "generated-index", - title: "Feature Service API", - slug: "/apis/resources/feature_service_v2", - description: - 'This API is intended to manage features for ZITADEL. Feature settings that are available on multiple "levels", such as instance and organization. The higher level instance acts as a default for the lower level. When a feature is set on multiple levels, the lower level takes precedence. Features can be experimental where ZITADEL will assume a sane default, such as disabled. When over time confidence in such a feature grows, ZITADEL can default to enabling the feature. As a final step we might choose to always enable a feature and remove the setting from this API, reserving the proto field number. Such removal is not considered a breaking change. Setting a removed field will effectively result in a no-op.\n', - }, - items: sidebar_api_feature_service_v2, - }, - { - type: "category", - label: "Organization", - link: { - type: "generated-index", - title: "Organization Service API", - slug: "/apis/resources/org_service/v2", - description: - "This API is intended to manage organizations for ZITADEL. \n", - }, - items: sidebar_api_org_service_v2, - }, - { - type: "category", - label: "Organization (Beta)", - link: { - type: "generated-index", - title: "Organization Service beta API", - slug: "/apis/resources/org_service/v2beta", - description: - "This API is intended to manage organizations for ZITADEL. \n", - }, - items: sidebar_api_org_service_v2beta, - }, - { - type: "category", - label: "Identity Provider", - link: { - type: "generated-index", - title: "Identity Provider Service API", - slug: "/apis/resources/idp_service_v2", - description: - "This API is intended to manage identity providers (IdPs) for ZITADEL.\n", - }, - items: sidebar_api_idp_service_v2, - }, - { - type: "category", - label: "Web Key", - link: { - type: "generated-index", - title: "Web Key Service API", - slug: "/apis/resources/webkey_service_v2", - description: - "This API is intended to manage web keys for a ZITADEL instance, used to sign and validate OIDC tokens.\n" + - "\n"+ - "The public key endpoint (outside of this service) is used to retrieve the public keys of the active and inactive keys.\n", - }, - items: sidebar_api_webkey_service_v2 - }, - { - type: "category", - label: "Action (Beta)", - link: { - type: "generated-index", - title: "Action Service API (Beta)", - slug: "/apis/resources/action_service_v2", - description: - "This API is intended to manage custom executions and targets (previously known as actions) in a ZITADEL instance.\n" + - "\n" + - "This service is in beta state. It can AND will continue breaking until a stable version is released.\n"+ - "\n" + - "The version 2 of actions provide much more options to customize ZITADELs behaviour than previous action versions.\n" + - "Also, v2 actions are available instance-wide, whereas previous actions had to be managed for each organization individually\n" + - "ZITADEL doesn't restrict the implementation languages, tooling and runtime for v2 action executions anymore.\n" + - "Instead, it calls external endpoints which are implemented and maintained by action v2 users.\n"+ - "\n" + - "Please make sure to enable the `actions` feature flag on your instance to use this service and that you're running Zitadel V3.", - }, - items: sidebar_api_actions_v2, - }, - { - type: "category", - label: "Project (Beta)", - link: { - type: "generated-index", - title: "Project Service API (Beta)", - slug: "/apis/resources/project_service_v2", - description: - "This API is intended to manage projects and subresources for ZITADEL. \n" + - "\n" + - "This service is in beta state. It can AND will continue breaking until a stable version is released.", - }, - items: sidebar_api_project_service_v2, - }, - { - type: "category", - label: "Instance (Beta)", - link: { - type: "generated-index", - title: "Instance Service API (Beta)", - slug: "/apis/resources/instance_service_v2", - description: - "This API is intended to manage instances, custom domains and trusted domains in ZITADEL.\n" + - "\n" + - "This service is in beta state. It can AND will continue breaking until a stable version is released.\n"+ - "\n" + - "This v2 of the API provides the same functionalities as the v1, but organised on a per resource basis.\n" + - "The whole functionality related to domains (custom and trusted) has been moved under this instance API." - , - }, - items: sidebar_api_instance_service_v2, - }, - { - type: "category", - label: "App (Beta)", - link: { - type: "generated-index", - title: "Application Service API (Beta)", - slug: "/apis/resources/application_service_v2", - description: - "This API lets you manage Zitadel applications (API, SAML, OIDC).\n"+ - "\n"+ - "The API offers generic endpoints that work for all app types (API, SAML, OIDC), "+ - "\n"+ - "This API is in beta state. It can AND will continue breaking until a stable version is released.\n" - }, - items: sidebar_api_app_v2, - }, - { - type: "category", - label: "Authorizations (Beta)", - link: { - type: "generated-index", - title: "Authorization Service API (Beta)", - slug: "/apis/resources/authorization_service_v2", - description: - "AuthorizationService provides methods to manage authorizations for users within your projects and applications.\n" + - "\n" + - "For managing permissions and roles for ZITADEL internal resources, like organizations, projects,\n" + - "users, etc., please use the InternalPermissionService."+ - "\n"+ - "This API is in beta state. It can AND will continue breaking until a stable version is released.\n" - }, - items: sidebar_api_authorization_service_v2, - }, - { - type: "category", - label: "Permissions (Beta)", - link: { - type: "generated-index", - title: "Permission Service API (Beta)", - slug: "/apis/resources/permission_service_v2", - description: - "This API is intended to manage internal permissions in ZITADEL.\n" + - "\n"+ - "This API is in beta state. It can AND will continue breaking until a stable version is released.\n" - }, - items: sidebar_api_permission_service_v2, - }, + "apis/migration_v1_to_v2" ], }, {