# Operate API Maker Using API

> Learn how to manage API Maker programmatically using its dedicated management API, secured with a communication token.

Source: https://docs.apimaker.dev/v1/docs/am-resources/operate-api-maker-using-api.html

API Maker can be operated programmatically via a dedicated management API. This allows external systems or scripts to perform administrative operations—such as creating or updating admin users—without using the UI.

## Configuration

To enable this feature:

1. Go to **Root Settings → Deployment Settings → API Access**.
2. Check the **Operate API Maker Using API** checkbox.
3. Set a **Communication Token** (minimum 48 characters). Use the **Generate** button to auto-generate a secure token.
4. Save the settings.

> **Warning**
>
> The Communication Token acts as the authentication secret for all management API calls. Keep it confidential and rotate it if compromised. Changing it immediately invalidates any existing integrations using the old token.

---

## API Endpoint

```text
POST {API_MAKER_HOST}/api/sites/root-user-settings/operate-api-maker-using-api
```

**Example:**
```text
POST http://api-maker.example.com/api/sites/root-user-settings/operate-api-maker-using-api
```

---

## Request

### Headers

| Header         | Value              | Required |
|----------------|--------------------|----------|
| `Content-Type` | `application/json` | Yes      |

### Request Body Structure

| Field       | Type     | Required | Description                                                                        |
|-------------|----------|----------|------------------------------------------------------------------------------------|
| `token`     | `string` | Yes      | The Communication Token configured in Deployment Settings. Minimum 48 characters. |
| `operation` | `string` | Yes      | The operation to perform. See [Supported Operations](https://docs.apimaker.dev/v1/docs/am-resources/operate-api-maker-using-api.html#supported-operations) below. |
| `payload`   | `object` | Depends  | Operation-specific data. See each operation's payload table for required fields.   |

---

## Supported Operations

| Operation            | Description                        |
|----------------------|------------------------------------|
| [`CREATE_ADMIN_USER`](https://docs.apimaker.dev/v1/docs/am-resources/operate-api-maker-using-api.html#create_admin_user)  | Creates a new admin user.          |
| [`UPDATE_ADMIN_USER`](https://docs.apimaker.dev/v1/docs/am-resources/operate-api-maker-using-api.html#update_admin_user)  | Updates an existing admin user.    |
| [`DELETE_ADMIN_USER`](https://docs.apimaker.dev/v1/docs/am-resources/operate-api-maker-using-api.html#delete_admin_user)  | Permanently deletes an admin user. |
| [`UPDATE_SECRET`](https://docs.apimaker.dev/v1/docs/am-resources/operate-api-maker-using-api.html#update_secret)          | Updates the secret for an admin user. |

---

### `CREATE_ADMIN_USER`

Creates a new admin user in API Maker. On success, the system also performs a git pull for the user's repository, saves their secret, and generates a deployment hook — all returned in the response.

**Sample Request:**
```json
{
    "token": "aBcDe_FgHiJ_KlMnO_PqRsT_UvWxY_ZaBcD_EfGhI_JkLmN_OpQrS",
    "operation": "CREATE_ADMIN_USER",
    "payload": {
        "user": {
            "name": "John Doe",
            "email": "john@example.com",
            "password": "securePassword123",
            "apiPath": "john_doe",
            "gitUrlWithCredentials": "https://username:access_token@github.com/username/repo.git",
            "gitCommitUserEmail": "john@example.com",
            "gitBranch": "main"
        },
        "secret": {
            "name": "Default",
            "keysCode": ""
        }
    }
}
```

#### `payload` Fields

| Field    | Type     | Required | Description                                       |
|----------|----------|----------|---------------------------------------------------|
| `user`   | `object` | Yes      | Object containing the new admin user's details.   |
| `secret` | `object` | No       | Optional object for initial secret configuration. |

#### `payload.user` Fields

| Field                   | Type     | Required | Description                                                                                          |
|-------------------------|----------|----------|------------------------------------------------------------------------------------------------------|
| `name`                  | `string` | Yes      | Full name of the user.                                                                               |
| `email`                 | `string` | Yes      | Email address of the user. Must be unique.                                                           |
| `password`              | `string` | Yes      | Plain-text password. API Maker encrypts it before storing.                                           |
| `apiPath`               | `string` | Yes      | Unique path segment for this user's APIs. Allowed characters: `[a-z, 0-9, _]`. Example: `john_doe`. |
| `gitUrlWithCredentials` | `string` | No       | Git repository URL with embedded credentials. Example: `https://user:token@github.com/user/repo.git`. Stored encrypted. |
| `gitCommitUserEmail`    | `string` | No       | Email used in git commits for this user.                                                             |
| `gitBranch`             | `string` | No       | Default git branch. Example: `main`.                                                                 |

#### `payload.secret` Fields

| Field      | Type     | Required | Description                                         |
|------------|----------|----------|-----------------------------------------------------|
| `name`     | `string` | Yes      | Secret name. Example: `Default`.                    |
| `keysCode` | `string` | No       | Application secrets code associated with this user. |

#### Response — Success `200`

```json
{
    "success": true,
    "statusCode": 200,
    "data": {
        "userResponse": {
            "guid": "01KP2MCKX5DNBGM7RCAASM3BMQ",
            "name": "John Doe",
            "email": "john@example.com",
            "apiPath": "john_doe",
            "settings": {
                "sandbox": {
                    "dependencies": {
                        "nodeJS": []
                    }
                },
                "allowedOrigins": []
            },
            "gitCommitUserEmail": "john@example.com",
            "gitBranch": "main",
            "isDebuggingEnabled": false,
            "userType": "ADMIN",
            "active": true,
            "_id": "69dc7c7ead52c49d2086d81e",
            "id": "69dc7c7ead52c49d2086d81e"
        },
        "gitPullResponse": true,
        "secretSaveResponse": true,
        "deploymentHookResponse": {
            "hookUrl": "6MgUnOSSqR36JTU9M7LON4BcbSvwxn4r",
            "hookAccessToken": "ASIQ4BJOHDl9RRUE5DH6cIuyvCUJQwCM",
            "hookSecret": "lIfV52PsStG3Nq4Wx2tWqmFd3uL0QOSU",
            "deploymentUrl": "http://__ip_address__:38246/api/sites/deploy/john_doe/6MgUnOSSqR36JTU9M7LON4BcbSvwxn4r?token=ASIQ4BJOHDl9RRUE5DH6cIuyvCUJQwCM&secret=lIfV52PsStG3Nq4Wx2tWqmFd3uL0QOSU&branch=main"
        }
    }
}
```

#### Response Fields

| Field                                         | Type      | Description                                                                        |
|-----------------------------------------------|-----------|------------------------------------------------------------------------------------|
| `data.userResponse`                           | `object`  | The created user record.                                                           |
| `data.userResponse.guid`                      | `string`  | Globally unique identifier for the user.                                           |
| `data.userResponse.name`                      | `string`  | Name of the created user.                                                          |
| `data.userResponse.email`                     | `string`  | Email of the created user.                                                         |
| `data.userResponse.apiPath`                   | `string`  | API path assigned to the user.                                                     |
| `data.userResponse.userType`                  | `string`  | Role of the user. Will be `ADMIN`.                                                 |
| `data.userResponse.active`                    | `boolean` | Whether the user account is active.                                                |
| `data.userResponse._id`                       | `string`  | Database identifier of the created user.                                           |
| `data.gitPullResponse`                        | `boolean` | `true` if the initial git pull was successful.                                     |
| `data.secretSaveResponse`                     | `boolean` | `true` if the secret was saved successfully.                                       |
| `data.deploymentHookResponse`                 | `object`  | Auto-generated deployment hook details for this user.                              |
| `data.deploymentHookResponse.hookUrl`         | `string`  | Unique hook URL token for this user's deployment endpoint.                         |
| `data.deploymentHookResponse.hookAccessToken` | `string`  | Access token to authenticate deployment hook calls.                                |
| `data.deploymentHookResponse.hookSecret`      | `string`  | Secret used to verify the deployment hook request.                                 |
| `data.deploymentHookResponse.deploymentUrl`   | `string`  | Full deployment webhook URL. Replace `__ip_address__` with your server IP.         |

---

### `UPDATE_ADMIN_USER`

Updates an existing admin user in API Maker. The user to update is located using the `find` criteria, and the fields in `updateData` are applied to the matched user.

**Sample Request:**
```json
{
    "token": "aBcDe_FgHiJ_KlMnO_PqRsT_UvWxY_ZaBcD_EfGhI_JkLmN_OpQrS",
    "operation": "UPDATE_ADMIN_USER",
    "payload": {
        "find": {
            "apiPath": "john_doe"
        },
        "updateData": {
            "name": "John Doe Updated",
            "email": "john.updated@example.com",
            "password": "newPassword123",
            "apiPath": "john_doe_updated",
            "gitUrlWithCredentials": "https://username:access_token@github.com/username/repo.git",
            "gitCommitUserEmail": "john.updated@example.com",
            "gitBranch": "main"
        }
    }
}
```

#### `payload` Fields

| Field        | Type     | Required | Description                                                              |
|--------------|----------|----------|--------------------------------------------------------------------------|
| `find`       | `object` | Yes      | Criteria to locate the user to update.                                   |
| `updateData` | `object` | Yes      | Fields to update on the matched user. Only provided fields are changed.  |

#### `payload.find` Fields

| Field     | Type     | Required | Description                                                         |
|-----------|----------|----------|---------------------------------------------------------------------|
| `apiPath` | `string` | Yes      | The current `apiPath` of the user to find. Must match exactly.      |

#### `payload.updateData` Fields

| Field                   | Type     | Required | Description                                                                                              |
|-------------------------|----------|----------|----------------------------------------------------------------------------------------------------------|
| `name`                  | `string` | No       | Updated full name of the user.                                                                           |
| `email`                 | `string` | No       | Updated email address. Must be unique.                                                                   |
| `password`              | `string` | No       | New plain-text password. API Maker encrypts it before storing. Omit to keep the existing password.       |
| `apiPath`               | `string` | No       | New API path. Allowed characters: `[a-z, 0-9, _]`. Changing this renames the user's API path.           |
| `gitUrlWithCredentials` | `string` | No       | Updated Git repository URL with embedded credentials. Stored encrypted.                                  |
| `gitCommitUserEmail`    | `string` | No       | Updated email used in git commits for this user.                                                         |
| `gitBranch`             | `string` | No       | Updated default git branch.                                                                              |

#### Response — Success `200`

```json
{
    "success": true,
    "statusCode": 200,
    "data": {
        "_id": "69dca794c282e099a4e6bbd3",
        "guid": "01KP2YX78WY1DQ62VTB4Y8T17E",
        "name": "John Doe Updated",
        "email": "john.updated@example.com",
        "apiPath": "john_doe_updated",
        "settings": {
            "allowedOrigins": [],
            "sandbox": {
                "automaticSandboxRestartInSeconds": null,
                "dependencies": {
                    "nodeJS": []
                },
                "sandboxCountOverrideAdmin": 1
            },
            "dockerFile": "",
            "hashOfRunCommand": "46252046",
            "hashOfDockerfile": "1089711499"
        },
        "gitCommitUserEmail": "john.updated@example.com",
        "gitBranch": "main",
        "isDebuggingEnabled": false,
        "userType": "ADMIN",
        "active": true,
        "__v": 0,
        "executedMigrationScripts": {
            "Migration 1": true
        }
    }
}
```

#### Response Fields

| Field                                  | Type      | Description                                                                      |
|----------------------------------------|-----------|----------------------------------------------------------------------------------|
| `data._id`                             | `string`  | Database identifier of the updated user.                                         |
| `data.guid`                            | `string`  | Globally unique identifier for the user.                                         |
| `data.name`                            | `string`  | Updated name of the user.                                                        |
| `data.email`                           | `string`  | Updated email of the user.                                                       |
| `data.apiPath`                         | `string`  | Updated API path of the user.                                                    |
| `data.userType`                        | `string`  | Role of the user. e.g. `ADMIN`.                                                  |
| `data.active`                          | `boolean` | Whether the user account is active.                                              |
| `data.isDebuggingEnabled`              | `boolean` | Whether sandbox debug mode is enabled for this user.                             |
| `data.gitCommitUserEmail`              | `string`  | Git commit email of the user.                                                    |
| `data.gitBranch`                       | `string`  | Default git branch of the user.                                                  |
| `data.settings`                        | `object`  | User sandbox and origin settings.                                                |
| `data.settings.allowedOrigins`         | `array`   | List of allowed CORS origins for this user.                                      |
| `data.settings.sandbox`                | `object`  | Sandbox configuration for this user.                                             |
| `data.settings.sandbox.sandboxCountOverrideAdmin` | `number` | Override for the number of sandboxes allocated to this user.        |
| `data.settings.sandbox.automaticSandboxRestartInSeconds` | `number\|null` | Interval in seconds for automatic sandbox restart. `null` if not set. |
| `data.settings.sandbox.dependencies.nodeJS` | `array` | List of Node.js package dependencies for this user's sandbox.             |
| `data.executedMigrationScripts`        | `object`  | Map of migration script names to their execution status (`true` = executed).    |

---

### `DELETE_ADMIN_USER`

Permanently deletes an existing admin user from API Maker. The user is located by their `apiPath`.

> **Danger**
>
> This operation is irreversible. All data associated with the user will be permanently removed.

**Sample Request:**
```json
{
    "token": "aBcDe_FgHiJ_KlMnO_PqRsT_UvWxY_ZaBcD_EfGhI_JkLmN_OpQrS",
    "operation": "DELETE_ADMIN_USER",
    "payload": {
        "apiPath": "john_doe"
    }
}
```

#### `payload` Fields

| Field     | Type     | Required | Description                                              |
|-----------|----------|----------|----------------------------------------------------------|
| `apiPath` | `string` | Yes      | The `apiPath` of the user to delete. Must match exactly. |

#### Response — Success `200`

```json
{
    "success": true,
    "statusCode": 200,
    "data": true
}
```

#### Response Fields

| Field  | Type      | Description                                      |
|--------|-----------|--------------------------------------------------|
| `data` | `boolean` | `true` if the user was successfully deleted.     |

---

### `UPDATE_SECRET`

Updates the secrets code for an existing admin user, identified by their `apiPath`.

**Sample Request:**
```json
{
    "token": "aBcDe_FgHiJ_KlMnO_PqRsT_UvWxY_ZaBcD_EfGhI_JkLmN_OpQrS",
    "operation": "UPDATE_SECRET",
    "payload": {
        "apiPath": "john_doe",
        "keysCode": "your-secrets-code-here"
    }
}
```

#### `payload` Fields

| Field      | Type     | Required | Description                                                   |
|------------|----------|----------|---------------------------------------------------------------|
| `apiPath`  | `string` | Yes      | The `apiPath` of the user whose secret will be updated.       |
| `keysCode` | `string` | Yes      | The new secrets code to apply to the user.                    |

#### Response — Success `200`

```json
{
    "success": true,
    "statusCode": 200,
    "data": true
}
```

#### Response Fields

| Field  | Type      | Description                                           |
|--------|-----------|-------------------------------------------------------|
| `data` | `boolean` | `true` if the secret was successfully updated.        |

---

## Error Responses

The following error responses apply to all operations.

#### Invalid Token — `401`

```json
{
    "success": false,
    "statusCode": 401,
    "errors": [
        { "message": "Unauthorized. Invalid communication token." }
    ]
}
```

#### Feature Disabled — `403`

```json
{
    "success": false,
    "statusCode": 403,
    "errors": [
        { "message": "Operate API Maker using API feature is not enabled." }
    ]
}
```

---

## Validation Rules

### Top-level Fields

| Field       | Rule                                                                          |
|-------------|-------------------------------------------------------------------------------|
| `token`     | Required. Must be a `string`. Minimum 48 characters.                         |
| `operation` | Required. Must be one of: `CREATE_ADMIN_USER`, `UPDATE_ADMIN_USER`, `DELETE_ADMIN_USER`, `UPDATE_SECRET`. |
| `payload`   | Required. Must be an `object`.                                                |

### `CREATE_ADMIN_USER` — `payload` Fields

| Field    | Rule                                                         |
|----------|--------------------------------------------------------------|
| `user`   | Required. Must be an `object` containing admin user details. |
| `secret` | Optional. Must be an `object` if provided.                   |

### `CREATE_ADMIN_USER` — `payload.user` Fields

| Field                   | Rule                                                      |
|-------------------------|-----------------------------------------------------------|
| `name`                  | Required. Must be a `string`.                             |
| `email`                 | Required. Must be a valid email `string`.                 |
| `password`              | Required. Must be a `string`. Minimum 4 characters.      |
| `apiPath`               | Required. Must be a `string`. Allowed: `[a-z, 0-9, _]`. |
| `gitUrlWithCredentials` | Optional. Must be a `string` if provided.                |
| `gitCommitUserEmail`    | Optional. Must be a `string` if provided.                |
| `gitBranch`             | Optional. Must be a `string` if provided.                |

### `CREATE_ADMIN_USER` — `payload.secret` Fields

| Field      | Rule                                      |
|------------|-------------------------------------------|
| `name`     | Required. Must be a `string`.             |
| `keysCode` | Optional. Must be a `string` if provided. |

### `UPDATE_ADMIN_USER` — `payload` Fields

| Field        | Rule                                                                         |
|--------------|------------------------------------------------------------------------------|
| `find`       | Required. Must be an `object`.                                               |
| `updateData` | Required. Must be an `object`. At least one field must be present.           |

### `UPDATE_ADMIN_USER` — `payload.find` Fields

| Field     | Rule                                    |
|-----------|-----------------------------------------|
| `apiPath` | Required. Must be a `string`.           |

### `UPDATE_ADMIN_USER` — `payload.updateData` Fields

| Field                   | Rule                                                      |
|-------------------------|-----------------------------------------------------------|
| `name`                  | Optional. Must be a `string` if provided.                |
| `email`                 | Optional. Must be a valid email `string` if provided.    |
| `password`              | Optional. Must be a `string`. Minimum 4 characters.      |
| `apiPath`               | Optional. Must be a `string`. Allowed: `[a-z, 0-9, _]`. |
| `gitUrlWithCredentials` | Optional. Must be a `string` if provided.                |
| `gitCommitUserEmail`    | Optional. Must be a `string` if provided.                |
| `gitBranch`             | Optional. Must be a `string` if provided.                |

---

### `DELETE_ADMIN_USER` — `payload` Fields

| Field     | Rule                                              |
|-----------|---------------------------------------------------|
| `apiPath` | Required. Must be a `string`. Must match exactly. |

### `UPDATE_SECRET` — `payload` Fields

| Field      | Rule                          |
|------------|-------------------------------|
| `apiPath`  | Required. Must be a `string`. |
| `keysCode` | Required. Must be a `string`. |

---

## Security Notes

- This endpoint does **not** require an AM user session or JWT token. Authentication is performed solely via the `token` field in the request body.
- Always use HTTPS in production to prevent token exposure.
- The Communication Token should be at least 48 characters. The built-in generator creates a strong token exceeding this minimum.
- `gitUrlWithCredentials` is stored encrypted in the database.
- The `deploymentUrl` in the `CREATE_ADMIN_USER` response contains sensitive tokens. Store it securely and never expose it in client-side code.