docs(apps): extend docs with new features

Author: Sebastian Sauerer

apps/building-apps/components/custom-action.md

@@ -0,0 +1,77 @@
+---
+title: Custom Action
+hide_title: true
+sidebar_position: 5
+---
+
+# Custom Automated Action
+
+Extend epilot's automation capabilities with custom actions that integrate seamlessly into the platform's workflow engine.
+
+## What Are Custom Actions?
+
+Epilot provides a powerful automation engine that allows you to create complex workflows and processes. Custom Actions are specialized components that can be added to these workflows, enabling you to perform specific tasks or integrations that are not available out-of-the-box. Customers can install these actions to enhance their automation capabilities, allowing for tailored solutions that fit their unique business needs. 
+
+With a custom action you can extend the epilot platform by adding new functionality that can be used in automation workflows. This allows you to create custom processing steps, integrations with external systems, or any other specialized functionality that enhances the epilot experience.
+
+## Why Use Custom Actions?
+Custom Actions provide several key benefits:
+- **Tailored Functionality**: Create specific actions that address unique business requirements
+- **Seamless Integration**: Actions fit naturally into epilot's automation workflows, enhancing existing processes
+- **Reusability**: Once created, actions can be reused across multiple workflows, reducing the time to set up new automations
+- **Community Sharing**: Share your custom actions with the epilot community, allowing others to benefit from your innovations
+
+
+## How to Create a Custom Action
+
+## External Integration
+
+### How To Integrate External Systems
+A custom action with an external integration is basically a webhook (POST) request to your defined system. 
+You can either:
+1. Trigger some asynchronous processing in your system, or
+2. Update epilot data with an access token built from the permission/role you can define (see [Permissions](/apps/building-apps/configure-permissions)).
+
+The payload of the is the follinwg
+```json
+{
+  "type": "external_integration",
+  "timestamp": "2022-11-03T20:26:10.344522Z",
+  "data": {
+    "org_id": "", // The ID of the organization that the action is executed in
+    "entity": "", // The entity type that the action is executed on, e.g. "opportunity", "contact","contract", etc.
+    "action_config": {},
+    "app_config": {}, 
+    "app_options": {}, // The options configured by the user when installing the app
+    "execution_id": "",
+    "execution_status": "",
+    "exection_action_id": "",
+    "trigger_event": "", // information about the calling event, e.g. "opportunity.created", "opportunity.updated", etc.
+  }
+}
+```
+
+additional you will get 4 headers specified by epilot:
+```http
+webhook-signature	v1a,puLZGVBm1MhSFz/kpgDsbt56DqanAAEg5Y5pgkVaz2d9WTbp6sGpo64qJFm8DWE8fo85b3cOs0CvV9v4WseUBw==
+webhook-timestamp	1749649159
+webhook-id	msg_245c477923600038edb96d07f9d95f77
+
+optional: x-epilot-token: ey...
+```
+
+The `webhook-*` headers are used to verify and check the authenticity of the request. See more about [how to secure external integrations](#how-external-integrations-are-secured-asymmetric-signature) below.
+
+The `x-epilot-token` is an access token that is generated based on the permissions and roles defined in your app configuration. This token allows you to securely access epilot data and perform actions on behalf of the user. (expires after 10 min)
+
+### Example: Sync Data With Your Platform And Write Back To epilot entites
+To create a custom action that syncs data with your platform and writes back to epilot entities, you can follow these steps:
+1. **Define the Action**: Create a new custom action in your app configuration with the type `external_integration`.
+2. **Define the Permissions**: Specify the permissions required for the action to access the necessary data in epilot.
+
+Now whenever a customer installs your App and invokes the custom action, the request will be sent to your external system with the payload described above. Your system can then process the request, perform the necessary operations (e.g., syncing data), and respond accordingly. By specifying the previous permission an access token is attached to the request. You can use that token and our [official SDK](https://github.com/epilot-dev/sdk-js) to write back to epilot entities.
+
+### How External Integrations Are Secured (Asymmetric Signature)
+To ensure that external integrations are secure, epilot uses an asymmetric signature mechanism. This involves generating a unique signature for each request that is sent to the external system. The signature is created using a private key that is known only to the epilot platform, and it is verified by the external system using a corresponding [public key](https://app.sls.epilot.io/v1/public/.well-known/public-key). This ensures that only authorized requests are processed, and it prevents unauthorized access to the external system. 
+
+To secure the endpoint our custom action is calling, you need to verify the signature of the request. We recommend to use the `verifyEpilotSignature` function by our App SDK as it handles the verification process for you. This function checks the signature against the public key and ensures that the request is valid. We use a standard way to sign & verify the requests according to the [webhook spec](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md).

apps/building-apps/components/custom-journey-block.md

@@ -1,7 +1,7 @@
 ---
 title: Journey Blocks
 hide_title: true
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # Custom Journey Blocks

apps/building-apps/components/portal-extension.md

@@ -1,11 +1,9 @@
 ---
 title: Portal Extensions
 hide_title: true
-sidebar_position: 4
+sidebar_position: 6
 ---
 
-<p>&nbsp;</p>
-
 <h1 align="center">Portal Extensions</h1>
 
 <p align="center">Enhance epilot portals with custom functionality and integrations</p>

apps/building-apps/configure-permissions.md

@@ -0,0 +1,47 @@
+---
+title: Permissions
+hide_title: true
+sidebar_position: 3
+---
+
+# Permissions
+
+Learn how to configure permissions your App requires to function properly. When building an app for the epilot platform, you may need to request specific permissions to access certain features or data. This guide will help you understand how to configure these permissions effectively.
+
+## What Are Permissions?
+Permissios in epilot are used to control access to various features and data within the platform. When you create an app, you can specify which permissions your app requires to function correctly. This ensures that users have the necessary access rights to use your app without encountering permission-related issues.
+
+## How to Configure Permissions For Your App
+To configure permissions for your app, you need to create a role in your own organization and specify which grants (permissions) this role should have. This role can then be assigned to users who will be using your app.
+
+### Step 1: Create a Role
+1. Go to the **Access Management** section of your epilot organization (under settings).
+2. Navigate to the **Roles** tab.
+3. Click on **New Role**.
+4. Enter a name for the role (e.g., "App User Role").
+5. Click **Save** to create the role.
+
+:::info
+We eventually introduce a new dedicated **App Role**, but for now please select the **User Role** for the role type.
+:::
+
+### Step 2: Configure Permissions
+1. After creating the role, you will see a list of available permissions (grants).
+2. Go to your App configuration in the epilot platform.
+3. In the **Permissions** section, select the role you created in Step 1. and save the changes.
+
+## How To Use Permissions in Your App
+
+Once your App is installed, a role you specified is automatically created in the customer's organization. This role will have the permissions you configured in Step 2. 
+
+Now every component has different options to access those permissions. For example the Custom Action component can access the permissions through the `x-epilot-token` header in the http request. This token contains the necessary information to authenticate and authorize the action being performed.
+
+Check the specific component documentation for details on how to access permissions in your app.
+
+## Supported Permissions by Component Type
+
+| Component Type            | Permissions Supported |
+|---------------------------|-----------------------|
+| Custom Journey Block      | No                   |
+| Portal Extension          | No                   |
+| Custom Action  | Yes                   |