diff --git a/docs/docs/apis/actionsv2/execution-local.md b/docs/docs/apis/actions/v3/testing-locally.md similarity index 92% rename from docs/docs/apis/actionsv2/execution-local.md rename to docs/docs/apis/actions/v3/testing-locally.md index 26325add57..7662c2bfe0 100644 --- a/docs/docs/apis/actionsv2/execution-local.md +++ b/docs/docs/apis/actions/v3/testing-locally.md @@ -1,5 +1,5 @@ --- -title: Actions v2 example execution locally +title: Test Actions Locally --- In this guide, you will create a ZITADEL execution and target. After a user is created through the API, the target is called. @@ -52,7 +52,7 @@ What happens here is only a target which prints out the received request, which As you see in the example above the target is created with HTTP and port '8090' and if we want to use it as webhook, the target can be created as follows: -[Create a target](/apis/resources/action_service_v3/action-service-create-target) +[Create a target](/apis/resources/action_service_v3/zitadel-actions-create-target) ```shell curl -L -X POST 'https://$CUSTOM-DOMAIN/v3alpha/targets' \ @@ -75,7 +75,7 @@ Save the returned ID to set in the execution. To call the target just created before, with the intention to print the request used for user creation by the user V2 API, we define an execution with a method condition. -[Set an execution](/apis/resources/action_service_v3/action-service-set-execution) +[Set an execution](/apis/resources/action_service_v3/zitadel-actions-set-execution) ```shell curl -L -X PUT 'https://$CUSTOM-DOMAIN/v3alpha/executions' \ @@ -116,7 +116,7 @@ curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2/users/human' \ }' ``` -Should print out something like, also described under [Sent information Request](./introduction#sent-information-request): +Should print out something like, also described under [Sent information Request](./usage#sent-information-request): ```shell { "fullMethod": "/zitadel.user.v2.UserService/AddHumanUser", diff --git a/docs/docs/apis/actionsv2/introduction.md b/docs/docs/apis/actions/v3/usage.md similarity index 79% rename from docs/docs/apis/actionsv2/introduction.md rename to docs/docs/apis/actions/v3/usage.md index c3e3b2144e..686c9d5445 100644 --- a/docs/docs/apis/actionsv2/introduction.md +++ b/docs/docs/apis/actions/v3/usage.md @@ -1,8 +1,19 @@ --- -title: Actions V2 +title: Using Actions --- -This page describes the options you have when defining ZITADEL Actions V2. +The Action API provides a flexible mechanism for customizing and extending the functionality of ZITADEL. By allowing you to define targets and executions, you can implement custom workflows triggered on an API requests and responses, events or specific functions. + +**How it works:** +- Create Target +- Set Execution with condition and target +- Custom Code will be triggered and executed + +**Use Cases:** +- User Management: Automate provisioning user data to external systems when users are crreated, updated or deleted. +- Security: Implement IP blocking or rate limiting based on API usage patterns. +- Extend Workflows: Automatically setup resources in your application, when a new organization in ZITADEL is created. +- Token extension: Add custom claims to the tokens. ## Endpoints @@ -51,7 +62,7 @@ There are different types of Targets: `InterruptOnError` means that the Execution gets interrupted if any of the calls return with a status code >= 400, and the next Target will not be called anymore. -The API documentation to create a target can be found [here](/apis/resources/action_service_v3/action-service-create-target) +The API documentation to create a target can be found [here](/apis/resources/action_service_v3/zitadel-actions-create-target) ## Execution @@ -65,7 +76,7 @@ The condition can be defined for 4 types of processes: - `Functions`, handling specific functionality in the logic of ZITADEL - `Events`, after a specific event happened and was stored in ZITADEL -The API documentation to set an Execution can be found [here](/apis/resources/action_service_v3/action-service-set-execution) +The API documentation to set an Execution can be found [here](/apis/resources/action_service_v3/zitadel-actions-set-execution) ### Condition Best Match @@ -147,19 +158,19 @@ For Request and Response there are 3 levels the condition can be defined: - `All`, handling any request or response under the ZITADEL API The available conditions can be found under: -- [All available Methods](/apis/resources/action_service_v3/action-service-list-execution-methods), for example `/zitadel.user.v2.UserService/AddHumanUser` -- [All available Services](/apis/resources/action_service_v3/action-service-list-execution-services), for example `zitadel.user.v2.UserService` +- [All available Methods](/apis/resources/action_service_v3/zitadel-actions-list-execution-methods), for example `/zitadel.user.v2.UserService/AddHumanUser` +- [All available Services](/apis/resources/action_service_v3/zitadel-actions-list-execution-services), for example `zitadel.user.v2.UserService` ### Condition for Functions Replace the current Actions with the following flows: -- [Internal Authentication](../actions/internal-authentication) -- [External Authentication](../actions/external-authentication) -- [Complement Token](../actions/complement-token) -- [Customize SAML Response](../actions/customize-samlresponse) +- [Internal Authentication](/apis/actions/internal-authentication) +- [External Authentication](/apis/actions/external-authentication) +- [Complement Token](/apis/actions/complement-token) +- [Customize SAML Response](/apis/actions/customize-samlresponse) -The available conditions can be found under [all available Functions](/apis/resources/action_service_v3/action-service-list-execution-functions). +The available conditions can be found under [all available Functions](/apis/resources/action_service_v3/zitadel-actions-list-execution-functions). ### Condition for Events diff --git a/docs/sidebars.js b/docs/sidebars.js index 38596d4bfc..8c83f9bf1d 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -745,10 +745,20 @@ module.exports = { slug: "/apis/resources/action_service_v3", description: "This API is intended to manage custom executions and targets (previously known as actions) in a ZITADEL instance.\n" + + "The version 3 of actions provide much more options to customize ZITADELs behaviour than previous action versions.\n" + + "Also, v3 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 v3 action executions anymore.\n" + + "Instead, it calls external endpoints which are implemented and maintained by action v3 users.\n" + "\n" + "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/action_service_v3/sidebar.ts"), + items: [{ + type: "doc", + id: "apis/actions/v3/usage", + }, { + type: "doc", + id: "apis/actions/v3/testing-locally", + }].concat(require("./docs/apis/resources/action_service_v3/sidebar.ts")), }, { type: "category", @@ -815,12 +825,6 @@ module.exports = { "apis/actions/objects", ], }, - { - type: "category", - label: "Actions V2", - collapsed: false, - items: ["apis/actionsv2/introduction", "apis/actionsv2/execution-local"], - }, { type: "doc", label: "gRPC Status Codes", diff --git a/docs/vercel.json b/docs/vercel.json index ab0202a3f8..15bd2499e8 100644 --- a/docs/vercel.json +++ b/docs/vercel.json @@ -24,6 +24,8 @@ { "source": "/docs/apis/auth/:slug*", "destination": "/docs/apis/resources/auth/:slug*", "permanent": true }, { "source": "/docs/apis/system/:slug*", "destination": "/docs/apis/resources/system/:slug*", "permanent": true }, { "source": "/docs/apis/admin/:slug*", "destination": "/docs/apis/resources/admin/:slug*", "permanent": true }, + { "source": "/docs/apis/actionsv2/introduction", "destination": "/docs/apis/actions/v3/usage", "permanent": true }, + { "source": "/docs/apis/actionsv2/execution-local", "destination": "/docs/apis/actions/v3/testing-locally", "permanent": true }, { "source": "/docs/guides/integrate/human-users", "destination": "/docs/guides/integrate/login", "permanent": true }, { "source": "/docs/guides/solution-scenarios/device-authorization", "destination": "/docs/guides/integrate/login/oidc/device-authorization", "permanent": true }, { "source": "/docs/guides/integrate/oauth-recommended-flows", "destination": "/docs/guides/integrate/login/oidc/oauth-recommended-flows", "permanent": true },