# Automation Hub

The Automation Hub API provides endpoints for managing hub settings, analytics, and shareable link authentication for public marketplace access.

## Overview

The Automation Hub API includes three main areas:

* **Settings**: Configure hub appearance, behavior, and access controls (admin only)
* **Analytics**: Track template usage and performance metrics (see [Analytics API](https://github.com/Appmixer-ai/appmixer-docs-gitbook/blob/6.4/api/analytics.md))
* **Shareable Links**: Enable public access via email-based authentication with OTP tokens

## Hub Settings

### Get Settings

<mark style="color:blue;">`GET`</mark> `http://[API-URL]/automation-hub/settings`

Retrieve the current Automation Hub settings. All authenticated users can read settings, but sensitive fields (like email allow lists) are filtered for non-admin users.

```bash
curl -XGET "http://[API-URL]/automation-hub/settings" \
  -H "Authorization: Bearer [ACCESS_TOKEN]"
```

{% tabs %}
{% tab title="200: OK Settings found" %}

```javascript
{
  "id": "default",
  "settings": {
    "sharing": {
      "allowedEmails": [  // Only visible to admin users
        "user@example.com",
        "team@company.com"
      ]
    },
    "theme": {
      "primaryColor": "#007bff",
      "logoUrl": "https://example.com/logo.png"
    },
    "customField": "any-value"  // Settings support flexible schema
  },
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-04-20T14:45:00.000Z"
}
```

{% endtab %}

{% tab title="200: OK No settings" %}

```javascript
{
  "id": "default",
  "settings": {},
  "createdAt": null,
  "updatedAt": null
}
```

{% endtab %}
{% endtabs %}

**Field Filtering:**

* **Admin users**: See all settings including `sharing.allowedEmails`
* **Regular users**: Sensitive fields are automatically filtered from the response

### Update Settings

<mark style="color:green;">`POST`</mark> `http://[API-URL]/automation-hub/settings`

Create or update Automation Hub settings. This endpoint performs an upsert operation. Admin token required.

```bash
curl -XPOST "http://[API-URL]/automation-hub/settings" \
  -H "Authorization: Bearer [ADMIN_TOKEN]" \
  -H "Content-type: application/json" \
  -d '{
    "settings": {
      "sharing": {
        "allowedEmails": ["user@example.com", "team@company.com"]
      },
      "theme": {
        "primaryColor": "#007bff"
      }
    }
  }'
```

#### Request Body

| Name                                       | Type   | Description                                          |
| ------------------------------------------ | ------ | ---------------------------------------------------- |
| settings<mark style="color:red;">\*</mark> | object | Settings object with flexible schema                 |
| settings.sharing.allowedEmails             | array  | Email addresses allowed to access Hub via share link |

{% tabs %}
{% tab title="200: OK" %}

```javascript
{
  "id": "default",
  "settings": {
    "sharing": {
      "allowedEmails": ["user@example.com", "team@company.com"]
    },
    "theme": {
      "primaryColor": "#007bff"
    }
  },
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-04-22T09:15:00.000Z"
}
```

{% endtab %}

{% tab title="400: Bad Request" %}

```javascript
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "\"settings.sharing.allowedEmails[0]\" must be a valid email"
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}

```javascript
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Missing authentication"
}
```

{% endtab %}

{% tab title="403: Forbidden" %}

```javascript
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient scope"
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Flexible Settings Schema**

The `settings` object supports any properties, allowing you to add custom fields without backend changes. Only `settings.sharing.allowedEmails` has validation (must be array of valid email addresses).
{% endhint %}

### Delete Settings

<mark style="color:red;">`DELETE`</mark> `http://[API-URL]/automation-hub/settings`

Delete all Automation Hub settings and reset to defaults. Admin token required.

```bash
curl -XDELETE "http://[API-URL]/automation-hub/settings" \
  -H "Authorization: Bearer [ADMIN_TOKEN]"
```

{% tabs %}
{% tab title="204: No Content" %}
Settings successfully deleted.
{% endtab %}

{% tab title="401: Unauthorized" %}

```javascript
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Missing authentication"
}
```

{% endtab %}

{% tab title="403: Forbidden" %}

```javascript
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient scope"
}
```

{% endtab %}
{% endtabs %}

## Shareable Links

Shareable links allow you to provide public access to your Automation Hub marketplace using email-based authentication with one-time passwords (OTP). Users receive activation links via email to authenticate without traditional login credentials.

### Architecture

1. **Email Allow List**: Admin configures allowed emails in hub settings
2. **Request Login**: User requests access with their email
3. **Activation Link**: System sends time-limited activation code
4. **Token Generation**: User activates link to receive JWT token with OTP flag
5. **Virtual User**: System creates virtual user account automatically

### Request Login

<mark style="color:green;">`POST`</mark> `http://[API-URL]/automation-hub/share/request-login`

Request an activation link for email-based login. No authentication required. Rate limited by email and IP address.

```bash
curl -XPOST "http://[API-URL]/automation-hub/share/request-login" \
  -H "Content-type: application/json" \
  -d '{ "email": "user@example.com" }'
```

#### Request Body

| Name                                    | Type   | Description                        |
| --------------------------------------- | ------ | ---------------------------------- |
| email<mark style="color:red;">\*</mark> | string | Email address (max 255 characters) |

{% tabs %}
{% tab title="200: OK Auto-send enabled" %}

```javascript
{
  "success": true,
  "message": "Activation link sent to your email"
}
```

Email will be sent automatically with the activation link.
{% endtab %}

{% tab title="200: OK Manual mode" %}

```javascript
{
  "success": true,
  "code": "a1b2c3d4e5f6",
  "link": "https://your-hub.com/automation-hub/share/activate?code=a1b2c3d4e5f6",
  "expiresIn": 3600
}
```

When `AUTOMATION_HUB_AUTO_SEND_EMAIL` is disabled, the link is returned directly.
{% endtab %}

{% tab title="403: Forbidden" %}

```javascript
{
  "error": "Email not authorized. Please contact your administrator."
}
```

The email is not on the allow list configured in hub settings.
{% endtab %}

{% tab title="429: Too Many Requests" %}

```javascript
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many requests for this email address. Please try again in a few minutes."
}
```

Rate limit exceeded. Separate limits apply per email and per IP address.
{% endtab %}

{% tab title="500: Internal Server Error" %}

```javascript
{
  "error": "Failed to send activation email. Please try again."
}
```

Email sending failed (SMTP or Cloud Email API error).
{% endtab %}
{% endtabs %}

**Rate Limits:**

* Per email: Configurable via `AUTOMATION_HUB_RATE_LIMIT_REQUEST_LOGIN_EMAIL` (default: 5 requests per minute)
* Per IP: Configurable via `AUTOMATION_HUB_RATE_LIMIT_REQUEST_LOGIN_IP` (default: 20 requests per minute)

**Email Delivery:** The system automatically selects the email service:

* If `SMTP_HOST` is configured, uses SMTP
* Otherwise, uses Cloud Email API (requires `APPMIXER_CLOUD_EMAIL_API` and `APPMIXER_CLOUD_EMAIL_API_KEY`)

### Activate Link

<mark style="color:blue;">`GET`</mark> `http://[API-URL]/automation-hub/share/activate?code=[CODE]`

Activate the link, create or find virtual user, and return JWT token. No authentication required. Rate limited by IP address.

```bash
curl -XGET "http://[API-URL]/automation-hub/share/activate?code=a1b2c3d4e5f6"
```

#### Query Parameters

| Name                                   | Type   | Description                     |
| -------------------------------------- | ------ | ------------------------------- |
| code<mark style="color:red;">\*</mark> | string | Activation code from email link |

{% tabs %}
{% tab title="200: OK" %}

```javascript
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "507f1f77bcf86cd799439011",
    "email": "user@example.com",
    "username": "user@example.com"
  }
}
```

The JWT token includes an `otp: true` flag and can be used for authentication.
{% endtab %}

{% tab title="400: Bad Request" %}

```javascript
{
  "error": "Activation link has already been used"
}
```

Each activation link can only be used once.
{% endtab %}

{% tab title="404: Not Found" %}

```javascript
{
  "error": "Invalid or expired activation link"
}
```

The activation code is invalid or the link has expired.
{% endtab %}

{% tab title="429: Too Many Requests" %}

```javascript
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many activation attempts. Please try again in a few minutes."
}
```

Rate limit exceeded for IP address.
{% endtab %}
{% endtabs %}

**Rate Limits:**

* Per IP: Configurable via `AUTOMATION_HUB_RATE_LIMIT_ACTIVATE_IP` (default: 10 requests per minute)

**Virtual Users:**

* Automatically created on first activation
* Username and email set to the activation email address
* Flagged as virtual users in the system
* Can access only the Automation Hub marketplace

### Refresh Link

<mark style="color:green;">`POST`</mark> `http://[API-URL]/automation-hub/share/refresh`

Request a new activation link for users with expired tokens. Works exactly like `/request-login` but intended for users who already have an expired session. No authentication required. Rate limited by email and IP address.

```bash
curl -XPOST "http://[API-URL]/automation-hub/share/refresh" \
  -H "Content-type: application/json" \
  -d '{ "email": "user@example.com" }'
```

#### Request Body

| Name                                    | Type   | Description                        |
| --------------------------------------- | ------ | ---------------------------------- |
| email<mark style="color:red;">\*</mark> | string | Email address (max 255 characters) |

{% hint style="info" %}
**Refresh vs Request Login**

Both endpoints function identically but serve different use cases:

* `/request-login`: Initial access request
* `/refresh`: Token renewal for existing users

Both share the same allow list validation and rate limiting.
{% endhint %}

**Rate Limits:**

* Per email: Configurable via `AUTOMATION_HUB_RATE_LIMIT_REFRESH_EMAIL` (default: 5 requests per minute)
* Per IP: Configurable via `AUTOMATION_HUB_RATE_LIMIT_REFRESH_IP` (default: 20 requests per minute)

## Configuration

### Environment Variables

#### Email Configuration

**SMTP (Option 1):**

```bash
SMTP_HOST=smtp.example.com
SMTP_PORT=587                          # Default: 587
SMTP_USER=your-username
SMTP_PASS=your-password
MAILER_FROM_NAME=Appmixer              # Default: Appmixer
MAILER_FROM_EMAIL=noreply@appmixer.com # Default: noreply@appmixer.com
```

**Cloud Email API (Option 2):**

```bash
APPMIXER_CLOUD_EMAIL_API=https://api.appmixer.com/email
APPMIXER_CLOUD_EMAIL_API_KEY=your-api-key
```

The system automatically uses SMTP if `SMTP_HOST` is set, otherwise falls back to Cloud Email API.

#### Activation Link Settings

```bash
# Control email sending behavior
AUTOMATION_HUB_AUTO_SEND_EMAIL=true    # Default: true

# Activation link TTL (time-to-live) in seconds
AUTOMATION_HUB_ACTIVATION_LINK_TTL=3600  # Default: 3600 (1 hour)

# Custom activation URL (optional)
AUTOMATION_HUB_ACTIVATE_URL=https://your-domain.com/activate
# If not set, uses: ${APPMIXER_FE_URL}/automation-hub/share/activate
```

#### Rate Limiting

```bash
# Request login limits
AUTOMATION_HUB_RATE_LIMIT_REQUEST_LOGIN_EMAIL=5   # Default: 5 per minute
AUTOMATION_HUB_RATE_LIMIT_REQUEST_LOGIN_IP=20     # Default: 20 per minute

# Activate link limits
AUTOMATION_HUB_RATE_LIMIT_ACTIVATE_IP=10          # Default: 10 per minute

# Refresh link limits
AUTOMATION_HUB_RATE_LIMIT_REFRESH_EMAIL=5         # Default: 5 per minute
AUTOMATION_HUB_RATE_LIMIT_REFRESH_IP=20           # Default: 20 per minute
```

## Use Cases

### Public Marketplace Access

Enable public users to access your Automation Hub marketplace:

```bash
# 1. Configure email allow list (admin)
curl -XPOST "http://[API-URL]/automation-hub/settings" \
  -H "Authorization: Bearer [ADMIN_TOKEN]" \
  -H "Content-type: application/json" \
  -d '{
    "settings": {
      "sharing": {
        "allowedEmails": ["partner@company.com", "customer@example.com"]
      }
    }
  }'

# 2. User requests access (no auth)
curl -XPOST "http://[API-URL]/automation-hub/share/request-login" \
  -H "Content-type: application/json" \
  -d '{ "email": "partner@company.com" }'

# 3. User receives email, clicks link and activates
curl -XGET "http://[API-URL]/automation-hub/share/activate?code=a1b2c3d4e5f6"

# Returns JWT token for marketplace access
```

### Custom Hub Theming

Configure custom theme and branding:

```bash
curl -XPOST "http://[API-URL]/automation-hub/settings" \
  -H "Authorization: Bearer [ADMIN_TOKEN]" \
  -H "Content-type: application/json" \
  -d '{
    "settings": {
      "theme": {
        "primaryColor": "#007bff",
        "logoUrl": "https://example.com/logo.png",
        "companyName": "Acme Corp"
      },
      "marketplace": {
        "welcomeMessage": "Welcome to our integration marketplace",
        "categories": ["CRM", "Marketing", "Sales"]
      }
    }
  }'
```

### Programmatic Allow List Management

Dynamically manage email access:

```bash
# Get current settings
CURRENT=$(curl -s -XGET "http://[API-URL]/automation-hub/settings" \
  -H "Authorization: Bearer [ADMIN_TOKEN]")

# Add new email to allow list
curl -XPOST "http://[API-URL]/automation-hub/settings" \
  -H "Authorization: Bearer [ADMIN_TOKEN]" \
  -H "Content-type: application/json" \
  -d '{
    "settings": {
      "sharing": {
        "allowedEmails": [
          "existing@example.com",
          "new-user@example.com"
        ]
      }
    }
  }'
```

## Security

### Email Allow List

The email allow list provides the primary access control mechanism:

* Only emails on the list can request activation links
* Case-insensitive matching
* Constant-time response prevents email enumeration attacks
* Administrators manage the list via settings API

### Rate Limiting

Multiple rate limits protect against abuse:

* **Per Email**: Prevents spam to specific addresses
* **Per IP**: Prevents brute-force attacks from single source
* **Separate Limits**: Different limits for request, activate, and refresh operations

### Activation Link Security

Activation links include several security features:

* **Time-Limited**: Configurable TTL (default: 1 hour)
* **Single-Use**: Each code can only be activated once
* **Atomic Marking**: Race condition protection prevents double-use
* **Random Codes**: Cryptographically secure token generation

### Virtual Users

Virtual users have restricted capabilities:

* Created automatically on activation
* Limited to Automation Hub marketplace access
* Separated from regular user accounts
* JWT tokens include `otp: true` flag for identification

## Audit Logging

All hub settings operations are automatically logged:

**Settings Update:**

```
Automation hub settings updated.
```

**Settings Delete:**

```
Automation hub settings deleted.
```

Each audit log entry includes:

* Operation type (upsert/delete)
* Before and after state
* Timestamp and admin user who performed the action
* Full settings object (including sensitive fields)

See [Audit Logs](/appmixer-backoffice/audit-logs.md) for more information.

## Error Handling

### Common Errors

**Email Not Authorized (403)**

```javascript
{
  "error": "Email not authorized. Please contact your administrator."
}
```

**Solution**: Add email to allow list via settings API

**Rate Limit Exceeded (429)**

```javascript
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many requests for this email address. Please try again in a few minutes."
}
```

**Solution**: Wait 60 seconds before retrying

**Invalid Activation Code (404)**

```javascript
{
  "error": "Invalid or expired activation link"
}
```

**Solution**: Request new activation link via `/request-login` or `/refresh`

**Link Already Used (400)**

```javascript
{
  "error": "Activation link has already been used"
}
```

**Solution**: Request new activation link - each code can only be used once

### Email Sending Failures

If email sending fails:

1. Check SMTP configuration (host, port, credentials)
2. Verify Cloud Email API configuration (URL, API key)
3. Review server logs for detailed error messages
4. Ensure firewall allows outbound email connections


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.appmixer.com/api/automation-hub.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.