feat(api): move resource apis to beta (#6530)

Moves UserService, SessionService, SettingsService and OIDCService to beta state. This includes gRPC and HTTP path changes.
2025-08-12 01:47:33 +00:00 · 2023-09-13 14:43:01 +02:00
parent 841b21d9cd
commit be81570fb5
80 changed files with 324 additions and 311 deletions
--- a/docs/docs/apis/introduction.mdx
+++ b/docs/docs/apis/introduction.mdx
@@ -287,10 +287,15 @@ For easy copying to your reverse proxy configuration, here is the list of URL pa
 /oidc/v1/
 /saml/v2/
 /oauth/v2/
+/device
+/oidc/v1/
 /.well-known/openid-configuration
 /openapi/
-/v2alpha/
-/zitadel.user.v2alpha.UserService/
-/zitadel.session.v2alpha.SessionService/
-/zitadel.settings.v2alpha.SettingsService/
+/idps/callback
+/v2beta/
+/zitadel.user.v2beta.UserService/
+/zitadel.session.v2beta.SessionService/
+/zitadel.settings.v2beta.SettingsService/
+/zitadel.oidc.v2beta.OIDCService/
+/zitadel.org.v2beta.OrganizationService/
 ```
--- a/docs/docs/guides/integrate/login-ui/_list-mfa-options.mdx
+++ b/docs/docs/guides/integrate/login-ui/_list-mfa-options.mdx
@@ -8,7 +8,7 @@ Request Example:

 ```bash
 curl --request GET \
-  --url https://$ZITADEL_DOMAIN/v2alpha/settings/login \
+  --url https://$ZITADEL_DOMAIN/v2beta/settings/login \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''
 ```
--- a/docs/docs/guides/integrate/login-ui/_logout.mdx
+++ b/docs/docs/guides/integrate/login-ui/_logout.mdx
@@ -7,7 +7,7 @@ Send the session token in the body of the request.

 ```bash
 curl --request DELETE \
-  --url https://$ZITADEL_DOMAIN/v2alpha/sessions/218480890961985793 \
+  --url https://$ZITADEL_DOMAIN/v2beta/sessions/218480890961985793 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
--- a/docs/docs/guides/integrate/login-ui/_select-account.mdx
+++ b/docs/docs/guides/integrate/login-ui/_select-account.mdx
@@ -9,7 +9,7 @@ The list of session IDs can be sent in the “search sessions” request to get

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/sessions/search \
+  --url https://$ZITADEL_DOMAIN/v2beta/sessions/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
--- a/docs/docs/guides/integrate/login-ui/_update_session_webauthn.mdx
+++ b/docs/docs/guides/integrate/login-ui/_update_session_webauthn.mdx
@@ -8,7 +8,7 @@ Example Request:

 ```bash
 curl --request PATCH \
-  --url https://$ZITADEL_DOMAIN/v2alpha/sessions/218480890961985793 \
+  --url https://$ZITADEL_DOMAIN/v2beta/sessions/218480890961985793 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
--- a/docs/docs/guides/integrate/login-ui/external-login.mdx
+++ b/docs/docs/guides/integrate/login-ui/external-login.mdx
@@ -26,7 +26,7 @@ In the response, you will get an authentication URL of the provider you like.

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/idp_intents \
+  --url https://$ZITADEL_DOMAIN/v2beta/idp_intents \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -71,7 +71,7 @@ To get the information of the provider, make a request to ZITADEL.
 ### Request
 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/idp_intents/$INTENT_ID \
+  --url https://$ZITADEL_DOMAIN/v2beta/idp_intents/$INTENT_ID \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -127,7 +127,7 @@ This check requires that the previous step ended on the successful page and didn
 #### Request
 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/sessions \
+  --url https://$ZITADEL_DOMAIN/v2beta/sessions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\

@@ -158,7 +158,7 @@ The display name is used to list the linkings on the users.
 #### Request
 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/users/human \
+  --url https://$ZITADEL_DOMAIN/v2beta/users/human \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -196,7 +196,7 @@ If you want to link/connect to an existing account you can perform the add ident
 #### Request
 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/users/users/218385419895570689/links \
+  --url https://$ZITADEL_DOMAIN/v2beta/users/users/218385419895570689/links \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
--- a/docs/docs/guides/integrate/login-ui/mfa.mdx
+++ b/docs/docs/guides/integrate/login-ui/mfa.mdx
@@ -41,7 +41,7 @@ Request Example:

 ```bash
 curl --request POST \
-    --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER_ID/totp \
+    --url https://$ZITADEL_DOMAIN/v2beta/users/$USER_ID/totp \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer '"$TOKEN"''
    --header 'Content-Type: application/json' \
@@ -73,7 +73,7 @@ Request Example:

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER_ID/totp/verify \
+  --url https://$ZITADEL_DOMAIN/v2beta/users/$USER_ID/totp/verify \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''
  --header 'Content-Type: application/json' \
@@ -99,7 +99,7 @@ Example Request

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/sessions \
+  --url https://$ZITADEL_DOMAIN/v2beta/sessions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -136,7 +136,7 @@ More detailed information about the API: [Update session Documentation](/apis/re
 Example Request
 ```bash
 curl --request PATCH \
-  --url https://$ZITADEL_DOMAIN/v2alpha/sessions/$SESSION-ID \
+  --url https://$ZITADEL_DOMAIN/v2beta/sessions/$SESSION-ID \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
@@ -176,7 +176,7 @@ Example Request:

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER-ID/phone \
+  --url https://$ZITADEL_DOMAIN/v2beta/users/$USER-ID/phone \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -196,7 +196,7 @@ More detailed information about the API: [Verify phone](/apis/resources/user_ser
 Example Request:
 ```bash
 curl --request POST \
-    --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER-ID/phone/verify \
+    --url https://$ZITADEL_DOMAIN/v2beta/users/$USER-ID/phone/verify \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer '"$TOKEN"'' \
    --header 'Content-Type: application/json' \
@@ -214,7 +214,7 @@ More detailed information about the API: [Add OTP SMS for a user](/apis/resource
 Example Request:
 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER-ID/otp_sms \
+  --url https://$ZITADEL_DOMAIN/v2beta/users/$USER-ID/otp_sms \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json'
@@ -238,7 +238,7 @@ Example Request

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/sessions \
+  --url https://$ZITADEL_DOMAIN/v2beta/sessions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -265,7 +265,7 @@ Example Request

 ```bash
 curl --request PATCH \
-  --url https://$ZITADEL_DOMAIN/v2alpha/sessions/225307381909694507 \
+  --url https://$ZITADEL_DOMAIN/v2beta/sessions/225307381909694507 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -303,7 +303,7 @@ More detailed information about the API: [Add OTP Email for a user](/apis/resour
 Example Request:
 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER-ID/otp_email \
+  --url https://$ZITADEL_DOMAIN/v2beta/users/$USER-ID/otp_email \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json'
@@ -327,7 +327,7 @@ Example Request

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/sessions \
+  --url https://$ZITADEL_DOMAIN/v2beta/sessions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -354,7 +354,7 @@ Example Request

 ```bash
 curl --request PATCH \
-  --url https://$ZITADEL_DOMAIN/v2alpha/sessions/225307381909694507 \
+  --url https://$ZITADEL_DOMAIN/v2beta/sessions/225307381909694507 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -389,7 +389,7 @@ Request Example:

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER_ID/u2f \
+  --url https://$ZITADEL_DOMAIN/v2beta/users/$USER_ID/u2f \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''
  --header 'Content-Type: application/json' \
@@ -460,7 +460,7 @@ Example Request:
 ```bash

 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER_ID/u2f/$PASSKEY_ID \
+  --url https://$ZITADEL_DOMAIN/v2beta/users/$USER_ID/u2f/$PASSKEY_ID \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -500,7 +500,7 @@ Example Request

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/sessions \
+  --url https://$ZITADEL_DOMAIN/v2beta/sessions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
--- a/docs/docs/guides/integrate/login-ui/oidc-standard.mdx
+++ b/docs/docs/guides/integrate/login-ui/oidc-standard.mdx
@@ -50,7 +50,7 @@ With the ID from the redirect before you will now be able to get the information

 ```bash
 curl --request GET \
-  --url https://$ZITADEL_DOMAIN/v2alpha/oidc/auth_requests/V2_224908753244265546 \
+  --url https://$ZITADEL_DOMAIN/v2beta/oidc/auth_requests/V2_224908753244265546 \
  --header 'Authorization: Bearer '"$TOKEN"''\
 ```

@@ -95,7 +95,7 @@ Read more about the [Finalize Auth Request Documentation](/docs/apis/resources/o
 Make sure that the authorization header is from the same account that you originally sent in the client id header ```x-zitadel-login-client: <userid>``` on the authorize endpoint.
 ```bash
 curl --request POST \
-  --url $ZITADEL_DOMAIN/v2alpha/oidc/auth_requests/V2_224908753244265546 \
+  --url $ZITADEL_DOMAIN/v2beta/oidc/auth_requests/V2_224908753244265546 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
--- a/docs/docs/guides/integrate/login-ui/passkey.mdx
+++ b/docs/docs/guides/integrate/login-ui/passkey.mdx
@@ -34,7 +34,7 @@ Send either the sendLink or the returnCode (empty message) in the request body,

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER_ID/passkeys/registration_link \
+  --url https://$ZITADEL_DOMAIN/v2beta/users/$USER_ID/passkeys/registration_link \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -81,7 +81,7 @@ The code only has to be filled if the user did get a registration code.

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER_ID/passkeys \
+  --url https://$ZITADEL_DOMAIN/v2beta/users/$USER_ID/passkeys \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -185,7 +185,7 @@ Example Request:

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER_ID/passkeys/$PASSKEY_ID \
+  --url https://$ZITADEL_DOMAIN/v2beta/users/$USER_ID/passkeys/$PASSKEY_ID \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -223,7 +223,7 @@ More detailed information about the API: [Create Session Documentation](/apis/re
 Example Request:
 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/sessions \
+  --url https://$ZITADEL_DOMAIN/v2beta/sessions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
--- a/docs/docs/guides/integrate/login-ui/password-reset.mdx
+++ b/docs/docs/guides/integrate/login-ui/password-reset.mdx
@@ -28,7 +28,7 @@ Make sure to also include the URL Template to customize the reset link in the em

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER_ID/password_reset \
+  --url https://$ZITADEL_DOMAIN/v2beta/users/$USER_ID/password_reset \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -47,7 +47,7 @@ Send the request with asking for the return Code in the body of the request.
 #### Request
 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER_ID/password_reset \
+  --url https://$ZITADEL_DOMAIN/v2beta/users/$USER_ID/password_reset \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -95,7 +95,7 @@ In this case it requires additionally the current password instead of the verifi

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/users/$USER_ID/password \
+  --url https://$ZITADEL_DOMAIN/v2beta/users/$USER_ID/password \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
--- a/docs/docs/guides/integrate/login-ui/username-password.mdx
+++ b/docs/docs/guides/integrate/login-ui/username-password.mdx
@@ -16,7 +16,7 @@ First, we create a new user with a username and password. In the example below w

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/users/human \
+  --url https://$ZITADEL_DOMAIN/v2beta/users/human \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -104,7 +104,7 @@ Send it to the Get Session Endpoint to find out how the user has authenticated.

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2alpha/sessions \
+  --url https://$ZITADEL_DOMAIN/v2beta/sessions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -167,7 +167,7 @@ To update an existing session, add the session ID to the URL and the session tok

 ```bash
 curl --request PATCH \
-  --url https://$ZITADEL_DOMAIN/v2alpha/sessions/$SESSION_ID \
+  --url https://$ZITADEL_DOMAIN/v2beta/sessions/$SESSION_ID \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
--- a/docs/docusaurus.config.js
+++ b/docs/docusaurus.config.js
@@ -261,28 +261,28 @@ module.exports = {
            },
          },
          user: {
-            specPath: ".artifacts/openapi/zitadel/user/v2alpha/user_service.swagger.json",
+            specPath: ".artifacts/openapi/zitadel/user/v2beta/user_service.swagger.json",
            outputDir: "docs/apis/resources/user_service",
            sidebarOptions: {
              groupPathsBy: "tag",
            },
          },
          session: {
-            specPath: ".artifacts/openapi/zitadel/session/v2alpha/session_service.swagger.json",
+            specPath: ".artifacts/openapi/zitadel/session/v2beta/session_service.swagger.json",
            outputDir: "docs/apis/resources/session_service",
            sidebarOptions: {
              groupPathsBy: "tag",
            },
          },
          oidc: {
-            specPath: ".artifacts/openapi/zitadel/oidc/v2alpha/oidc_service.swagger.json",
+            specPath: ".artifacts/openapi/zitadel/oidc/v2beta/oidc_service.swagger.json",
            outputDir: "docs/apis/resources/oidc_service",
            sidebarOptions: {
              groupPathsBy: "tag",
            },
          },
          settings: {
-            specPath: ".artifacts/openapi/zitadel/settings/v2alpha/settings_service.swagger.json",
+            specPath: ".artifacts/openapi/zitadel/settings/v2beta/settings_service.swagger.json",
            outputDir: "docs/apis/resources/settings_service",
            sidebarOptions: {
              groupPathsBy: "tag",
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -507,57 +507,57 @@ module.exports = {
        },
        {
          type: "category",
-          label: "User lifecycle (alpha)",
+          label: "User lifecycle (Beta)",
          link: {
            type: "generated-index",
-            title: "User service API (Alpha)",
+            title: "User service API (Beta)",
            slug: "/apis/resources/user_service",
            description:
              "This API is intended to manage users 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 login.",
+              "This project is in beta state. It can AND will continue breaking until the services provide the same functionality as the current login.",
          },
          items: require("./docs/apis/resources/user_service/sidebar.js"),
        },
        {
          type: "category",
-          label: "Session lifecycle (Alpha)",
+          label: "Session lifecycle (Beta)",
          link: {
            type: "generated-index",
-            title: "Session service API (Alpha)",
+            title: "Session service API (Beta)",
            slug: "/apis/resources/session_service",
            description:
              "This API is intended to manage sessions 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 login.",
+              "This project is in beta state. It can AND will continue breaking until the services provide the same functionality as the current login.",
          },
          items: require("./docs/apis/resources/session_service/sidebar.js"),
        },
        {
          type: "category",
-          label: "OIDC lifecycle (Alpha)",
+          label: "OIDC lifecycle (Beta)",
          link: {
            type: "generated-index",
-            title: "OIDC service API (Alpha)",
+            title: "OIDC service API (Beta)",
            slug: "/apis/resources/oidc_service",
            description:
              "Get OIDC Auth Request details and create callback URLs.\n"+
              "\n"+
-              "This project is in alpha state. It can AND will continue breaking until the services provide the same functionality as the current login.",
+              "This project is in beta state. It can AND will continue breaking until the services provide the same functionality as the current login.",
          },
          items: require("./docs/apis/resources/oidc_service/sidebar.js"),
        },
        {
          type: "category",
-          label: "Settings lifecycle (alpha)",
+          label: "Settings lifecycle (Beta)",
          link: {
            type: "generated-index",
-            title: "Settings service API (Alpha)",
+            title: "Settings service API (Beta)",
            slug: "/apis/resources/settings_service",
            description:
              "This API is intended to manage settings in a ZITADEL instance.\n"+
              "\n"+
-              "This project is in alpha state. It can AND will continue to break until the services provide the same functionality as the current login.",
+              "This project is in beta state. It can AND will continue to break until the services provide the same functionality as the current login.",
          },
          items: require("./docs/apis/resources/settings_service/sidebar.js"),
        },