diff --git a/docs/docs/apis/actions.md b/docs/docs/apis/actions.md
deleted file mode 100644
index 4f4f562c27..0000000000
--- a/docs/docs/apis/actions.md
+++ /dev/null
@@ -1,107 +0,0 @@
----
-title: Actions
----
-
-This page describes the options you have when writing ZITADEL actions scripts.
-
-## Language
-ZITADEL interpretes the scripts as JavaScript.
-Make sure your scripts are ECMAScript 5.1(+) compliant.
-Go to the [goja GitHub page](https://github.com/dop251/goja) for detailed reference about the underlying library features and limitations.
-
-Actions do not have access to any libraries yet.
-Also, sending HTTP requests is not supported yet.
-[We plan to add such features in the future](https://zitadel.com/roadmap).
-
-## Flows
-
-Each flow type supports its own set of:
-- Triggers
-- Readable information
-- Writable information
-
-For reading and mutating state, the runtime executes the function that has the same name as the action.
-The function receives the JavaScript objects `ctx` and `api`.
-
-The object `ctx` provides readable information as object properties and by callable functions.
-The object `api` provides mutable properties and state mutating functions.
-
-The script of an action called **doSomething** should have a function called `doSomething` and look something like this:
-
-```js
-function doSomething(ctx, api){
-    // read from ctx and manipulate with api
-}
-```
-
-ZITADEL supports only the external authentication flow at the moment.
-[More flows are coming soon](https://zitadel.com/roadmap).
-
-### External authentication flow triggers
-
-- Post authentication: A user has authenticated externally. ZITADEL retrieved and mapped the external information.
-- Pre creation:  A user selected **Register** on the overview page after external authentication. ZITADEL did not create the user yet.
-- Post creation: A user selected **Register** on the overview page after external authentication. ZITADEL created the user.
-
-### External authentication flow context
-
-- `ctx.accessToken string`  
-  This can be an opaque token or a JWT
-- `ctx.idToken string`
-- `ctx.getClaim(string) any`  
-  Returns the requested claim
-- `ctx.claimsJSON() object`  
-  Returns the complete payload of the `ctx.idToken`
-
-### External authentication flow api
-
-- `api.setFirstName(string)`
-- `api.setLastName(string)`
-- `api.setNickName(string)`
-- `api.setDisplayName(string)`
-- `api.setPreferredLanguage(string)`
-- `api.setGender(Gender)`  
-- `api.setUsername(string)`  
-  This function is only available for the pre creation trigger
-- `api.setPreferredUsername(string)`  
-  This function is only available for the post authentication trigger
-- `api.setEmail(string)`
-- `api.setEmailVerified(bool)`
-- `api.setPhone(string)`
-- `api.setPhoneVerified(bool)`
-- `api.metadata array<Metadata>`  
-  Push entries.  
-- `api.userGrants array<UserGrant>`  
-  Push entries.  
-  This field is only available for the post creation trigger
-
-
-### External authentication flow types <!-- TODO: Are these types correct? -->
-
-- `Gender` is a code number
-
-| code | gender |
-| ---- | ------ |
-| 0 | unspecified |
-| 1 | female |
-| 2 | male |
-| 3 | diverse |
-
-- `UserGrant` is a JavaScript object
-
-```ts
-{
-    projectID: string,
-    projectGrantID: string,
-    roles: Array<string>,
-}
-```
-
-- `Metadata` is a JavaScript object with string values.
-  The string values must be Base64 encoded
-
-## Further reading
-
-- [Actions concept](../concepts/features/actions)
-- [Actions guide](../guides/manage/customize/behavior)
-- [Actions Marketplace: Find example actions to use in ZITADEL](https://github.com/zitadel/actions)
diff --git a/docs/docs/apis/actions/introduction.md b/docs/docs/apis/actions/introduction.md
new file mode 100644
index 0000000000..4d88c06111
--- /dev/null
+++ b/docs/docs/apis/actions/introduction.md
@@ -0,0 +1,54 @@
+---
+title: Actions
+---
+
+This page describes the options you have when writing ZITADEL actions scripts.
+
+## Language
+
+ZITADEL interpretes the scripts as JavaScript.
+Make sure your scripts are ECMAScript 5.1(+) compliant.
+Go to the [goja GitHub page](https://github.com/dop251/goja) for detailed reference about the underlying library features and limitations.
+
+You can find great snippets and examples which show how you can use actions in [this repository](https://github.com/zitadel/actions).
+
+Actions are a key feature to extend the functionality of ZITADEL and continuously improve the feature and expand the use cases. Check out our [roadmap](https://zitadel.com/roadmap) for more details.
+
+## Action
+
+The action object describes the logic defined by the user. Actions can be linked to multiple [triggers](#flows).
+
+The name of the action must corelate with the javascript function in the code section. This function will be called by ZITADEL.
+
+For reading and mutating state, the runtime executes the function that has the same name as the action.
+The function receives the JavaScript objects `ctx` and `api`.
+
+The object `ctx` provides readable information as object properties and by callable functions.
+The object `api` provides mutable properties and state mutating functions.
+
+The script of an action called **doSomething** should have a function called `doSomething` and look something like this:
+
+```js
+function doSomething(ctx, api){
+    // read from ctx and manipulate with api
+}
+```
+
+## Flows
+
+Flows are the links between an [action](#action) and a specific point during a user interaction with ZITADEL. These specific point are called [Trigger Types](#trigger-types).
+
+## Trigger Types
+
+Trigger types define the point during execution of request. Each trigger defines which readable information (`ctx`) and mutual properties (`api`) are passed into the called function as well as which libraries are available for the function. Each trigger type is described in the [available flow types section](#available-flow-types)
+
+## Available Flow Types
+
+Currently ZITADEL provides the following flows:
+
+- [Login](./login-flow.md)
+- [Register](./register-flow.md)
+
+## Available Modules inside Javascript
+
+- [HTTP module](./modules#http) to call API's
\ No newline at end of file
diff --git a/docs/docs/apis/actions/login-flow.md b/docs/docs/apis/actions/login-flow.md
new file mode 100644
index 0000000000..97eda02c2b
--- /dev/null
+++ b/docs/docs/apis/actions/login-flow.md
@@ -0,0 +1,51 @@
+---
+title: Login flows
+---
+
+## Complement Token
+
+This flow is executed during the creation of tokens and token introspection.
+
+### Pre Userinfo creation
+
+This trigger is called before userinfo are set in the token or response.
+
+#### Parameters of Pre Userinfo creation
+
+- `ctx`  
+  The first parameter contains the following fields:
+  - `v1`
+    - `user`
+      - `getMetadata()` [*metadataResult*](./objects#metadata-result)
+- `api`  
+  The second parameter contains the following fields:
+  - `v1`
+    - `userinfo`
+      - `setClaim(string, Any)`  
+        Key of the claim and any value
+    - `user`
+      - `setMetadata(string, Any)`  
+        Key of the metadata and any value
+
+### Pre access token creation
+
+This trigger is called before the claims are set in the access token and the token type is `jwt`.
+
+#### Parameters of Pre access token creation
+
+- `ctx`  
+  The first parameter contains the following fields:
+  - `v1`
+    - `user`
+      - `getMetadata()` [*metadataResult*](./objects#metadata-result)
+- `api`  
+  The second parameter contains the following fields:
+  - `v1`
+    - `claims`
+      - `setClaim(string, Any)`  
+        Sets any value if the key is not already present
+      - `appendLogIntoClaims(string)`  
+        Appends the entry into the claim `urn:zitadel:action:{action.name}:log` the value of the claim is an Array of *string*
+    - `user`
+      - `setMetadata(string, Any)`  
+        Key of the metadata and any value
diff --git a/docs/docs/apis/actions/modules.md b/docs/docs/apis/actions/modules.md
new file mode 100644
index 0000000000..62a1c93717
--- /dev/null
+++ b/docs/docs/apis/actions/modules.md
@@ -0,0 +1,53 @@
+---
+title: Modules
+---
+
+ZITADEL provides the following modules.
+
+## HTTP
+
+This module provides functionality to call REST APIs.
+
+### Import
+
+```js
+    let http = require('zitadel/http')
+```
+
+### `fetch()` function
+
+This function allows to call HTTP servers. The function does NOT fulfil the [Fetch API specification](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
+
+#### Parameters
+
+- `url` *string*
+- `options`  
+  **Optional**, containing custom settings that you want to apply to the request.
+  - `headers`  
+    Overwrites the default headers. One of the following types
+    - *map[string] string*  
+      The value is split into separate values after each comma `,`.
+    - *map[string] Array of string*  
+      The value is a string array
+    - default:
+      - `Content-Type`: `application/json`
+      - `Accept`: `application/json`
+  - `method`  
+    The request method. Allowed values are `GET`, `POST`, `PUT`, `DELETE`
+  - `body` *Object*  
+    JSON representation
+
+#### Response
+
+If the request was valid, an error will be thrown, otherwise a Response object will be returned.
+
+The object has the following fields and methods:
+
+- `status` *number*  
+  Status code of response
+- `body` *string*  
+  Return value
+- `json()` *Object*  
+  Returns the body as JSON object, or throws an error if the body is not a json object.
+- `text()` *string*  
+  Returns the body
diff --git a/docs/docs/apis/actions/objects.md b/docs/docs/apis/actions/objects.md
new file mode 100644
index 0000000000..6a1f4d14ed
--- /dev/null
+++ b/docs/docs/apis/actions/objects.md
@@ -0,0 +1,110 @@
+---
+title: Objects
+---
+
+## External User
+
+- `externalId` *string*  
+  User id from the identity provider
+- `externalIdpId` *string*  
+  Id of the identity provider
+- `human`
+  - `firstName` *string*
+  - `lastName` *string*
+  - `nickName` *string*
+  - `displayName` *string*
+  - `preferredLanguage` *string*  
+    In [RFC 5646](https://www.rfc-editor.org/rfc/rfc5646) fromat
+  - `email` *string*
+  - `isEmailVerified` *boolean*
+  - `phone` *string*
+  - `isPhoneVerified` *boolean*
+
+## metadata with value as bytes
+
+- `key` *string*
+- `value` Array of *byte*
+
+## metadata result
+
+- `count` *number*
+- `sequence` *number*
+- `timestamp` *Date*
+- `metadata` Array of [*metadata*](#metadata)
+
+## metadata
+
+- `creationDate` *Date*
+- `changeDate` *Date*
+- `resourceOwner` *string*
+- `sequence` *number*
+- `key` *string*
+- `value` `Any`
+
+## user grant
+
+- `projectId` *string*  
+  Required. Id of the project to be granted
+- `projectGrantId` *string*  
+  If the grant is for a project grant
+- `roles` Array of *string*  
+  Containing the roles
+
+## user
+
+- `id` *string*
+- `creationDate` *Date*
+- `changeDate` *Date*
+- `resourceOwner` *string*
+- `sequence` *number*  
+  Unsigned 64 bit integer
+- `state` *number*  
+  <ul><li>0: unspecified</li><li>1: active</li><li>2: inactive</li><li>3: deleted</li><li>4: locked</li><li>5: suspended</li><li>6: initial</li></ul>
+- `username` *string*
+- `loginNames` Array of *string*
+- `preferredLoginName` *string*
+- `human`  
+  Set if the user is human
+  - `firstName` *string*
+  - `lastName` *string*
+  - `nickName` *string*
+  - `displayName` *string*
+  - `avatarKey` *string*
+  - `preferredLanguage` *string*  
+    In [RFC 5646](https://www.rfc-editor.org/rfc/rfc5646) fromat
+  - `gender` *number*  
+    <ul><li>0: unspecified</li><li>1: female</li><li>2: male</li><li>3: diverse</li></ul>
+  - `email` *string*
+  - `isEmailVerified` *boolean*
+  - `phone` *string*
+  - `isPhoneVerified` *boolean*
+- `machine`  
+  Set if the user is a machine
+  - `name` *string*
+  - `description` *string*
+
+## human user
+
+- `id` *string*
+- `creationDate` *Date*
+- `changeDate` *Date*
+- `resourceOwner` *string*
+- `sequence` *number*
+- `state` *number*  
+  <ul><li>0: unspecified</li><li>1: active</li><li>2: inactive</li><li>3: deleted</li><li>4: locked</li><li>5: suspended</li><li>6: initial</li></ul>
+- `username` *string*
+- `loginNames` Array of *string*
+- `preferredLoginName` *string*
+- `profile`
+  - `firstName` *string*
+  - `lastName` *string*
+  - `nickName` *string*
+  - `displayName` *string*
+  - `preferredLanguage` *string*  
+    In [RFC 5646](https://www.rfc-editor.org/rfc/rfc5646) fromat
+- `email`
+  - `email` *string*
+  - `isEmailVerified` *boolean*
+- `phone`
+  - `phone` *string*
+  - `isPhoneVerified` *boolean*
diff --git a/docs/docs/apis/actions/register-flow.md b/docs/docs/apis/actions/register-flow.md
new file mode 100644
index 0000000000..6a440b6825
--- /dev/null
+++ b/docs/docs/apis/actions/register-flow.md
@@ -0,0 +1,112 @@
+---
+title: Register flows
+---
+
+## External Authentication
+
+This flow is executed if the user logs in using an [identity provider](../../guides/integrate/identity-brokering) or using a [jwt token](../../concepts/structure/jwt_idp).
+
+### Post Authentication
+
+A user has authenticated externally. ZITADEL retrieved and mapped the external information.
+
+#### Parameters of post authentication action
+
+- `ctx`  
+The first parameter contains the following fields
+  - `accessToken` *string*  
+    The access token which will be returned to the user. This can be an opaque token or a JWT
+  - `claimsJSON()` [*idTokenClaims*](../openidoauth/claims)  
+    Returns all claims of the id token
+  - `getClaim(key)` *Any*  
+    Returns the requested [id token claim](../openidoauth/claims)
+  - `idToken` *string*  
+    The id token which will be returned to the user
+  - `v1`
+    - `externalUser()` [*externalUser*](./objects#external-user)
+- `api`  
+  The second parameter contains the following fields
+  - `v1`
+    - `user`
+      - `appendMetadata(string, Any)`  
+        The first parameter represents the key and the second a value which will be stored
+  - `setFirstName(string)`  
+    Sets the first name
+  - `setLastName(string)`  
+    Sets the last name
+  - `setNickName(string)`  
+    Sets the nickname
+  - `setDisplayName(string)`  
+    Sets the display name
+  - `setPreferredLanguage(string)`  
+    Sets the preferred language. Please use the format defined in [RFC 5646](https://www.rfc-editor.org/rfc/rfc5646)
+  - `setPreferredUsername(string)`  
+    Sets the preferred username
+  - `setEmail(string)`  
+    Sets the email address of the user
+  - `setEmailVerified(boolean)`  
+    Sets the email address verified or unverified
+  - `setPhone(string)`  
+    Sets the phone number of the user
+  - `setPhoneVerified(boolean)`  
+    Sets the phone number verified or unverified
+  - `metadata`  
+    Array of [*metadata*](./objects#metadata-with-value-as-bytes). This function is deprecated, please use `api.v1.user.appendMetadata`
+
+### Pre Creation
+
+A user selected **Register** on the overview page after external authentication. ZITADEL did not create the user yet.
+
+#### Parameters of Pre Creation
+
+- `ctx`  
+  The first parameter contains the following fields
+  - `v1`
+    - `user` [*human*](./objects#human-user)
+- `api`  
+  The second parameter contains the following fields
+  - `metadata`  
+    Array of [*metadata*](./objects#metadata-with-value-as-bytes). This function is deprecated, please use `api.v1.user.appendMetadata`
+  - `setFirstName(string)`  
+    Sets the first name
+  - `setLastName(string)`  
+    Sets the last name
+  - `setNickName(string)`  
+    Sets the nick name
+  - `setDisplayName(string)`  
+    Sets the display name
+  - `setPreferredLanguage(string)`  
+    Sets the preferred language, the string has to be a valid language tag as defined in [RFC 5646](https://www.rfc-editor.org/rfc/rfc5646)
+  - `setGender(int)`  
+    Sets the gender.  
+    <ul><li>0: unspecified</li><li>1: female</li><li>2: male</li><li>3: diverse</li></ul>
+  - `setUsername(string)`  
+    Sets the username
+  - `setEmail(string)`  
+    Sets the email
+  - `setEmailVerified(bool)`  
+    If true the email set is verified without user interaction
+  - `setPhone(string)`  
+    Sets the phone number
+  - `setPhoneVerified(bool)`  
+    If true the phone number set is verified without user interaction
+  - `v1`
+    - `user`
+      - `appendMetadata(string, Any)`  
+        The first parameter represents the key and the second a value which will be stored
+
+### Post Creation
+
+A user selected **Register** on the overview page after external authentication and ZITADEL successfully created the user.
+
+#### Parameters of Post Creation
+
+- `ctx`  
+  The first parameter contains the following fields
+  - `v1`
+    - `getUser()` [*user*](./objects#user)
+- `api`  
+  The second parameter contains the following fields
+  - `userGrants` Array of [*userGrant*](./objects#user-grant)'s
+  - `v1`
+    - `appendUserGrant(`[`userGrant`](./objects#user-grant)`)`
diff --git a/docs/docs/concepts/features/actions.md b/docs/docs/concepts/features/actions.md
index 94dc9d247a..9e5ad3edf5 100644
--- a/docs/docs/concepts/features/actions.md
+++ b/docs/docs/concepts/features/actions.md
@@ -35,5 +35,5 @@ Within the JavaScript code, you can read and manipulate the state.
 ## Further reading
 
 - [Assign users a role after they register using an external identity provider](../../guides/manage/customize/behavior)
-- [Actions reference](../../apis/actions)
-- [Actions Marketplace: Find example actions to use in ZITADEL](https://github.com/zitadel/actions)
\ No newline at end of file
+- [Actions reference](../../apis/actions/introduction#action)
+- [Actions Marketplace: Find example actions to use in ZITADEL](https://github.com/zitadel/actions)
diff --git a/docs/docs/guides/manage/customize/behavior.md b/docs/docs/guides/manage/customize/behavior.md
index 91194a0fa1..5cb9f8086b 100644
--- a/docs/docs/guides/manage/customize/behavior.md
+++ b/docs/docs/guides/manage/customize/behavior.md
@@ -36,13 +36,13 @@ https://github.com/zitadel/actions/blob/main/examples/add_user_grant.js
 
 ## Run the action when a user registers
 
-Now, make the action hook into the [external authentication flow](../../../apis/actions#external-authentication-flow).
+Now, make the action hook into the [external authentication flow](../../../apis/actions/register-flow#external-authentication).
 
 1. In the **Flows <i class="las la-exchange-alt"></i>** section, select the **+ New** button.
-1. Select the **Flow Type** *External Authentication*.
-1. Select the **Trigger Type** *Post Creation*.
-1. In the **Actions** dropdown, check *addGrant*.
-1. Select the **Save** button.
+2. Select the **Flow Type** *External Authentication*.
+3. Select the **Trigger Type** *Post Creation*.
+4. In the **Actions** dropdown, check *addGrant*.
+5. Select the **Save** button.
 
 <!-- TODO: ## Test if your action works -->
 
@@ -51,4 +51,4 @@ New users automatically are assiged a role now if they register by authenticatin
 ## What's next?
 
 - [Read more about the concepts around actions](../../../concepts/features/actions)
-- [Read more about all the options you have with actions](../../../apis/actions)
\ No newline at end of file
+- [Read more about all the options you have with actions](../../../apis/actions/introduction)
\ No newline at end of file
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 05caff39de..d75dd75981 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -228,7 +228,6 @@ module.exports = {
           collapsed: true,
           items: ["apis/assets/assets"],
         },
-        "apis/actions",
       ],
     },
     {
@@ -249,6 +248,18 @@ module.exports = {
       collapsed: false,
       items: ["apis/saml/endpoints"],
     },
+    {
+      type: "category",
+      label: "Actions",
+      collapsed: false,
+      items: [
+        "apis/actions/introduction",
+        "apis/actions/modules",
+        "apis/actions/login-flow",
+        "apis/actions/register-flow",
+        "apis/actions/objects",
+      ]
+    },
     {
       type: "category",
       label: "Observability",