diff --git a/docs/docs/apis/apis/index.mdx b/docs/docs/apis/apis/index.mdx
new file mode 100644
index 0000000000..f0ba7e6e4d
--- /dev/null
+++ b/docs/docs/apis/apis/index.mdx
@@ -0,0 +1,12 @@
+---
+title: Core Resources
+sidebar_label: Core Resources
+---
+
+import DocCardList from '@theme/DocCardList';
+
+ZITADEL provides multiple APIs to manage the system, instances and resources such as users, projects and more.
+
+There are different versions and multiple services available:
+
+
\ No newline at end of file
diff --git a/docs/docs/apis/introduction.mdx b/docs/docs/apis/introduction.mdx
index de4173e001..c90435eed6 100644
--- a/docs/docs/apis/introduction.mdx
+++ b/docs/docs/apis/introduction.mdx
@@ -39,7 +39,7 @@ Refer to our guide to learn how to [build your own login UI](/docs/guides/integr
## ZITADEL APIs (resource-based)
-ZITADEL provides APIs for each [core resource](/docs/apis/resources):
+ZITADEL provides APIs for each [core resource](/docs/apis/v2):
- [User](/docs/apis/resources/user_service)
- [Session](/docs/apis/resources/session_service)
diff --git a/docs/docs/apis/v2.mdx b/docs/docs/apis/v2.mdx
new file mode 100644
index 0000000000..0b69707a19
--- /dev/null
+++ b/docs/docs/apis/v2.mdx
@@ -0,0 +1,12 @@
+---
+title: APIs V2 (Beta)
+---
+
+import DocCardList from '@theme/DocCardList';
+
+APIs V2 organize access by resources (users, settings, etc.), unlike context-specific V1 APIs.
+This simplifies finding the right API, especially for multi-organization resources.
+
+**Note**: V2 is currently in [Beta](/support/software-release-cycles-support#beta) and not yet generally available (breaking changes possible). Check individual services for availability.
+
+
\ No newline at end of file
diff --git a/docs/docs/apis/v3.mdx b/docs/docs/apis/v3.mdx
new file mode 100644
index 0000000000..aa3b328e45
--- /dev/null
+++ b/docs/docs/apis/v3.mdx
@@ -0,0 +1,15 @@
+---
+title: APIs V3 (Preview)
+---
+
+import DocCardList from '@theme/DocCardList';
+
+APIs (V3) organize access by resources (users, settings, etc.), unlike context-specific V1 APIs.
+This simplifies finding the right API, especially for multi-organization resources.
+V3 also offers more flexibility over the V2 API in these points:
+- User schema definition for custom user management.
+- Behavior customization (API call manipulation, webhooks).
+
+**Note**: V3 is currently in [Preview](/support/software-release-cycles-support#preview) and not yet generally available (breaking changes possible). Check individual services for availability.
+
+
\ No newline at end of file
diff --git a/docs/docs/support/software-release-cycles-support.md b/docs/docs/support/software-release-cycles-support.md
index d587e79fc9..87fbdd6527 100644
--- a/docs/docs/support/software-release-cycles-support.md
+++ b/docs/docs/support/software-release-cycles-support.md
@@ -51,7 +51,13 @@ Therefore, it's recommended to use caution when using Alpha and Beta software, a
Only features in General Availability will be covered by support services.
-We encourage our community to test Alpha and Beta software and provide feedback via our [Discord Chat](https://zitadel.com/chat).
+We encourage our community to check out Preview and test Alpha and Beta software and provide feedback via our [Discord Chat](https://zitadel.com/chat).
+
+### Preview
+
+The Preview state is our initial stage to document planned futures and collect early feedback on the design.
+Features are not yet implemented at all or availability is limited to designated testers.
+We recommend that users exercise caution when using Preview software and avoid using it for critical tasks, as support is limited during this phase.
### Alpha
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 23d64e833e..5b92639bae 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -521,38 +521,19 @@ module.exports = {
label: "Core Resources",
collapsed: false,
link: {
- type: "generated-index",
- title: "Core Resources",
- slug: "/apis/apis/",
- description:
- "ZITADEL provides multiple APIs to manage the system, instances and resources such as users, projects and more.\n" +
- "\n" +
- "There are multiple different versions and multiple services available:"+
- "\n" +
- "The resource based APIs are, as the name suggests, organized by resources such as users, session, settings and more.\n" +
- "These services are the future of the ZITADEL APIS and the best way to start integrating ZITADEL.\n" +
- "\n"+
- "The service based APIs are organized by UseCase/Context, such as Auth API for authenticated users,"+
- "Management API for organization managers, Admin API for instance managers and a System API for system managers.",
+ type: "doc",
+ id: "apis/apis/index",
},
items: [
{
type: "category",
- label: "Service Based (V1)",
+ label: "V1 (General Available)",
collapsed: false,
link: {
type: "generated-index",
- title: "Service Based APIs (V1)",
+ title: "APIs V1 (GA)",
slug: "/apis/services/",
- description:
- "The service based APIs are organized by UseCase/Context, such as Auth API for authenticated users,"+
- "Management API for organization managers, Admin API for instance managers and a System API for system managers.\n"+
- "\n"+
- "To improve the developer experience in managing the different resources, ZITADEL also offers Resource Based APIs (v2 and v3). "+
- "Those APIs focus on the resources themselves. For example they offer a User Service, which will give you the possibility " +
- "to search for users across multiple organizations.\n"+
- "Note that the Resource Based APIs are not yet generally available. Please check the corresponding service" +
- "for their state and functionality.",
+ description: "APIs V1 organize access by context (authenticated user, organisation, instance, system), unlike resource-specific V2 APIs.",
},
items: [
{
@@ -609,24 +590,11 @@ module.exports = {
},
{
type: "category",
- label: "Resource Based (V2)",
+ label: "V2 (Beta)",
collapsed: false,
link: {
- type: "generated-index",
- title: "Resource Based APIs (V2)",
- slug: "/apis/resources/",
- description:
- "The resource based APIs are, as the name suggest, organized by resources such as users, session, settings and more. "+
- "Check the list below to get an overview of all available resources.\n"+
- "\n"+
- "While the service based APIs (V1) work great for use cases in a specific context such as a single organization, " +
- "it's sometime difficult to know which API to use, particularly for resources across multiple organizations. "+
- "For instance, SearchUsers on an Instance level or on an Organization level.\n"+
- "This is exactly where the resource based APIs come in place, e.g. with the User Service, " +
- "where you're able to search all users and can provide the context (organization) yourself if needed or just search the whole instance.\n"+
- "\n"+
- "Note that these APIs are not yet generally available and therefore breaking changes might still occur.\n"+
- "Please check the corresponding service for more information on the state and availability.",
+ type: "doc",
+ id: "apis/v2",
},
items: [
{
@@ -689,68 +657,52 @@ module.exports = {
},
{
type: "category",
- label: "Resource Based (V3)",
+ label: "V3 (Preview)",
collapsed: false,
link: {
- type: "generated-index",
- title: "Resource Based APIs (V3)",
- slug: "/apis/resources_v3/",
- description:
- "The resource based APIs are, as the name suggests, organized by resources such as users, session, settings and more.\n"+
- "\n"+
- "While the service based APIs (V1) work great for use cases in a specific context such as a single organization, " +
- "it's sometime difficult to know which API to use, particularly for resources across multiple organizations. "+
- "For instance, SearchUsers on an Instance level or on an Organization level.\n"+
- "This is exactly where the resource based APIs come in place, e.g. with the User Service, " +
- "where you're able to search all users and can provide the context (organization) yourself if needed or just search the whole instance.\n"+
- "\n"+
- "Version 3 offers more customization than the V2 resource bases APIs. You can define your own user schema "+
- "to be able to manage users based on these schemas and customize various behaviors, such as manipulating "+
- "inbound API calls, call webhooks on different event and more with the execution service.\n"+
- "\n"+
- "Note that these APIs are not yet generally available and therefore breaking changes might still occur.\n"+
- "Please check the corresponding service for more information on the state and availability.",
+ type: "doc",
+ id: "apis/v3",
},
items: [
{
type: "category",
- label: "User Schema Lifecycle (Alpha)",
+ label: "User Schema Lifecycle (Preview)",
link: {
type: "generated-index",
- title: "User Schema Service API (Aplha)",
+ title: "User Schema Service API (Preview)",
slug: "/apis/resources/user_schema_service",
description:
"This API is intended to manage data schemas for users in a ZITADEL instance.\n" +
"\n" +
- "This project is in alpha state. It can AND will continue breaking until the service provides the same functionality as the v1 and v2 user services.",
+ "This project is in Preview state. It can AND will continue breaking until the service provides the same functionality as the v1 and v2 user services.",
},
items: require("./docs/apis/resources/user_schema_service_v3/sidebar.js"),
},
{
type: "category",
- label: "User Lifecycle (Alpha)",
+ label: "User Lifecycle (Preview)",
link: {
type: "generated-index",
- title: "User Service API (Aplha)",
+ title: "User Service API (Preview)",
slug: "/apis/resources/user_service_v3",
description:
"This API is intended to manage users with your own data schema in a ZITADEL instance.\n"+
"\n"+
- "This project is in alpha state. It can AND will continue breaking until the service provides the same functionality as the v1 and v2 user services."
+ "This project is in Preview state. It can AND will continue breaking until the service provides the same functionality as the v1 and v2 user services."
},
items: require("./docs/apis/resources/user_service_v3/sidebar.js"),
},
{
type: "category",
- label: "Execution Lifecycle (Alpha)",
+ label: "Execution Lifecycle (Preview)",
link: {
type: "generated-index",
- title: "Execution Service API (Alpha)",
+ title: "Execution Service API (Preview)",
slug: "/apis/resources/execution_service_v3",
description:
"This API is intended to manage custom executions (previously known as actions) in a ZITADEL instance.\n"+
"\n"+
- "This project is in alpha state. It can AND will continue breaking until the services provide the same functionality as the current actions.",
+ "This project is in Preview state. It can AND will continue breaking until the services provide the same functionality as the current actions.",
},
items: require("./docs/apis/resources/execution_service_v3/sidebar.js"),
},
diff --git a/proto/zitadel/execution/v3alpha/execution_service.proto b/proto/zitadel/execution/v3alpha/execution_service.proto
index 3384567e55..4e5cef9925 100644
--- a/proto/zitadel/execution/v3alpha/execution_service.proto
+++ b/proto/zitadel/execution/v3alpha/execution_service.proto
@@ -17,8 +17,8 @@ option go_package = "github.com/zitadel/zitadel/pkg/grpc/execution/v3alpha;execu
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
info: {
title: "Execution Service";
- version: "3.0-alpha";
- description: "This API is intended to manage custom executions (previously known as actions) in a ZITADEL instance. This project is in alpha state. It can AND will continue breaking until the services provide the same functionality as the current actions.";
+ version: "3.0-preview";
+ description: "This API is intended to manage custom executions (previously known as actions) in a ZITADEL instance. This project is in preview state. It can AND will continue breaking until the services provide the same functionality as the current actions.";
contact:{
name: "ZITADEL"
url: "https://zitadel.com"
diff --git a/proto/zitadel/user/schema/v3alpha/user_schema_service.proto b/proto/zitadel/user/schema/v3alpha/user_schema_service.proto
index 0ef1c9c5c5..16710641ee 100644
--- a/proto/zitadel/user/schema/v3alpha/user_schema_service.proto
+++ b/proto/zitadel/user/schema/v3alpha/user_schema_service.proto
@@ -18,8 +18,8 @@ option go_package = "github.com/zitadel/zitadel/pkg/grpc/user/schema/v3alpha";
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
info: {
title: "User Schema Service";
- version: "3.0-alpha";
- description: "This API is intended to manage data schemas for users in a ZITADEL instance. This project is in alpha state. It can AND will continue breaking until the service provides the same functionality as the v1 and v2 user services.";
+ version: "3.0-preview";
+ description: "This API is intended to manage data schemas for users in a ZITADEL instance. This project is in preview state. It can AND will continue breaking until the service provides the same functionality as the v1 and v2 user services.";
contact:{
name: "ZITADEL"
url: "https://zitadel.com"
diff --git a/proto/zitadel/user/v3alpha/user_service.proto b/proto/zitadel/user/v3alpha/user_service.proto
index 0e42460ae1..cb6989be05 100644
--- a/proto/zitadel/user/v3alpha/user_service.proto
+++ b/proto/zitadel/user/v3alpha/user_service.proto
@@ -21,8 +21,8 @@ option go_package = "github.com/zitadel/zitadel/pkg/grpc/user/v3alpha";
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
info: {
title: "User Service";
- version: "3.0-alpha";
- description: "This API is intended to manage users with your own data schema in a ZITADEL instance. This project is in alpha state. It can AND will continue breaking until the service provides the same functionality as the v1 and v2 user services.";
+ version: "3.0-preview";
+ description: "This API is intended to manage users with your own data schema in a ZITADEL instance. This project is in preview state. It can AND will continue breaking until the service provides the same functionality as the v1 and v2 user services.";
contact:{
name: "ZITADEL"
url: "https://zitadel.com"