ZITADEL Actions v2

By using ZITADEL Actions v2, you can modify ZITADEL's behavior on specific API calls, events, or functions. This is useful when you have special business requirements that ZITADEL does not support out-of-the-box.

<Callout> We're working on Actions continuously. In the [roadmap](https://zitadel.com/roadmap), you can see how we plan to expand and improve this feature. Please tell us about your needs to help us prioritize further improvements and features. </Callout> <Callout> To use Actions v2, activate the "Actions" [feature flag](/reference/api/feature/zitadel.feature.v2.FeatureService.SetInstanceFeatures) in order to manage the related resources.

Actions v2 will always be executed if available, even if the feature flag is switched off. To remove any Actions v2, the related Execution must be removed. </Callout>

Why Actions?

ZITADEL can't anticipate or solve every possible business rule and integration requirement for all users. Here are some examples:

• A business requires domain-specific data validation before a user can be created or authenticated.
• A business needs to automate tasks, such as assigning roles to users based on their ADFS 2016+ groups.
• A business needs to store metadata on a user, which is used for integrating applications.
• A business needs to restrict which users are allowed to register to a certain organization by their email domains.

With Actions, ZITADEL provides a way to address such scenarios.

How it works

There are three necessary components:

• Endpoint: An external endpoint with the desired logic. It can be anything, as long as it can receive an HTTP POST request.
• Target: A resource in ZITADEL containing all the necessary information about how to trigger an endpoint.
• Execution: A resource in ZITADEL specifying when to trigger which targets.

The process is that, at certain points, ZITADEL executes a defined Execution, which then calls the defined Target(s). This allows everyone to implement custom behavior for as many processes as needed.

Possible conditions for the Execution:

• Request: Reacts to or manipulates requests to ZITADEL, for example, by adding information to newly created users.
• Response: Reacts to or manipulates responses from ZITADEL, for example, provisioning newly created users to other systems.
• Function: Reacts to various functions in ZITADEL, replacing Actions.
• Event: Reacts to different events created in ZITADEL, for example, to inform someone if a user gets locked.

<Callout> Currently, defined Actions v2 will be executed in addition to [Actions](/concepts/features/actions). </Callout>

Migration

• Migrate Actions v1 to Actions v2

Further reading

• Actions v2 reference
• Actions v2 example execution for request
• Actions v2 example execution for request manipulation
• Actions v2 example execution for request signature check
• Actions v2 example execution for response
• Actions v2 example execution for response manipulation
• Actions v2 example execution for function
• Actions v2 example execution for function manipulation
• Actions v2 example execution for event

Example use cases:

The following repository contains various examples demonstrating how to use Actions v2 in different scenarios. It also includes a deployment script for testing the examples with Cloudflare Workers:

• Actions v2 examples