The Action Service API allows you to manage custom executions (previously known as actions) in a ZITADEL instance. Executions enable you to extend ZITADEL’s functionality by calling external endpoints at specific points in the request lifecycle.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/zitadel/zitadel/llms.txt
Use this file to discover all available pages before exploring further.
Base URL
Authentication
All endpoints require authentication using OAuth2 with the following scopes:openidurn:zitadel:iam:org:project:id:zitadel:aud
Key Concepts
Targets
A target defines an HTTP endpoint that ZITADEL will call. Each target includes:- Name: Human-readable identifier
- Endpoint URL: The URL to call
- Target Type: How the response is handled (webhook, call, or async)
- Timeout: Maximum duration for the request
- Payload Type: How the payload is formatted (JSON, JWT, or JWE)
Target Types
- REST Webhook: POST request where only the status code is checked. Body is ignored.
- REST Call: POST request where both status code and body are checked. Allows payload modification.
- REST Async: Asynchronous POST request. Response is not waited for or checked.
Executions
An execution defines when and which targets to call. Each execution includes:- Condition: When the execution should trigger (request, response, function, or event)
- Targets: Ordered list of target IDs to call
Conditions
Executions can be triggered by:- Request: Before a specific API method/service is processed
- Response: Before a response is returned from a method/service
- Function: When a specific function is called (replaces Actions v1)
- Event: When specific events occur in the system
Payload Security
Targets support three payload types:- JSON (default): Payload sent as JSON with
X-ZITADEL-Signatureheader for verification - JWT: Payload sent as signed JSON Web Token
- JWE: Payload sent as encrypted JWT using your public key
Available Operations
Target Management
- Create Target - Create a new target endpoint
- Update Target - Modify an existing target
- List Targets - Search for targets
Execution Management
- Set Execution - Configure when targets are called
- List Executions - View configured executions
Common Use Cases
IP Allowlist
Validate user IP addresses before allowing authentication:- Create a target pointing to your IP validation service
- Set up an execution on the login request
- Your service receives the IP and returns allow/deny
Custom Claims
Add custom claims to tokens:- Create a target that returns additional user data
- Set up an execution on token response
- ZITADEL merges the returned claims into the token
Audit Logging
Send events to external audit systems:- Create an async target pointing to your audit service
- Set up executions on critical events (user.created, login.succeeded, etc.)
- Events are sent without blocking the main flow
User Provisioning
Automate user provisioning to external systems:- Create a target for your provisioning endpoint
- Set up an execution on user.human.added event
- User data is sent to your system when created
Permissions
| Operation | Required Permission |
|---|---|
| Create Target | action.target.write |
| Update Target | action.target.write |
| Delete Target | action.target.delete |
| Get Target | action.target.read |
| List Targets | action.target.read |
| Set Execution | action.execution.write |
| List Executions | action.execution.read |