# Operate API Maker Using API

> Create, change and delete admin accounts of API Maker, and change their default secret, from a script - one route of the server, a communication token, four operations with their payloads, answers and errors.

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

A script or another system can create the admin accounts of API Maker, change them, delete them and change their default secret, without the admin panel. A hosting company gives each client an account this way, for example.

## Turn it on

1. **Open the setting** **Root Settings → Deployment Settings → API Access**, and tick **Operate API Maker Using API**.
2. **Set the communication token** 48 characters at least : **Generate** makes one.
3. **Save** The route answers from now on.

> **Warning : The token is the only key**
>
> The route asks for no session and no other token : whoever has the communication token can create and delete accounts. Keep it in a secret store, send it over HTTPS only, and change it when it may have leaked. A new token ends the integrations which use the old one at once.

## The route

```text
POST https://api.example.com/api/sites/root-user-settings/operate-api-maker-using-api
Content-Type: application/json
```

| Field of the body | What it is |
|---|---|
| `token` | The communication token, a text of 48 characters or more. |
| `operation` | `CREATE_ADMIN_USER`, `UPDATE_ADMIN_USER`, `DELETE_ADMIN_USER` or `UPDATE_SECRET`. |
| `payload` | An object : what the operation needs, below. |

## Create an account

`CREATE_ADMIN_USER` creates an admin account. It also pulls its Git repository when one is given, saves its secret, and makes its deployment hook : the answer holds all four.

```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": "" }
    }
}
```

| Field of `payload.user` | Rule |
|---|---|
| `name` | Required, a text. |
| `email` | Required, a valid email, not used by another account. |
| `password` | Required, 4 characters at least. Sent plain : API Maker encrypts it before it stores it. |
| `apiPath` | Required, unique : `a-z`, `0-9`, `_` and `-`. The path of the APIs of the account : `/api/schema/john_doe/…`. |
| `gitUrlWithCredentials` | Optional : the repository, with its credentials in the URL. Stored encrypted. |
| `gitCommitUserEmail`, `gitBranch` | Optional : the email of its commits, and its branch. |
| `insertDefaultData` | Optional, `true` by default. `false` leaves out the sample data of a new account (custom APIs, schemas, hooks, migration scripts) ; its default group and API user are made either way. |

`payload.secret` is optional : `name` (required in it, `Default`) and `keysCode`, the TypeScript of the [secret](https://docs.apimaker.dev/v4/docs/secrets/secrets.html).

**Answer**

```json
{
    "success": true,
    "statusCode": 200,
    "data": {
        "userResponse": {
            "guid": "01KP2MCKX5DNBGM7RCAASM3BMQ",
            "name": "John Doe",
            "email": "john@example.com",
            "apiPath": "john_doe",
            "gitCommitUserEmail": "john@example.com",
            "gitBranch": "main",
            "userType": "ADMIN",
            "active": true,
            "_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"
        }
    }
}
```

- `userResponse` is the account, without its password and its Git credentials.
- `gitPullResponse` and `secretSaveResponse` say whether the pull and the secret worked.
- `deploymentHookResponse` is the [deployment hook](https://docs.apimaker.dev/v4/docs/Git/git.html) of the account. In `deploymentUrl`, put the address of your server in place of `__ip_address__`. It carries the token and the secret of the hook : keep it out of client code.

## Change an account

`UPDATE_ADMIN_USER` finds the account by its `apiPath` and changes the fields of `updateData`. The fields left out stay as they are, the password too.

```json
{
    "token": "aBcDe_FgHiJ_KlMnO_PqRsT_UvWxY_ZaBcD_EfGhI_JkLmN_OpQrS",
    "operation": "UPDATE_ADMIN_USER",
    "payload": {
        "find": { "apiPath": "john_doe" },
        "updateData": {
            "name": "John Doe",
            "email": "john.doe@example.com",
            "password": "newPassword123",
            "gitBranch": "main"
        }
    }
}
```

- `find.apiPath` is required : the `apiPath` of the account as it is now.
- `updateData` takes the fields of `payload.user` above, with the same rules, one of them at least. A new `apiPath` changes the path of every API of the account.
- The answer is the account as it is after the change, in `data`.

## Delete an account

`DELETE_ADMIN_USER` deletes the account of an `apiPath`, and everything it owns.

> **Danger**
>
> There is no undo : the account and all its data are gone.

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

The answer is `{ "success": true, "statusCode": 200, "data": true }`.

## Change the secret of an account

`UPDATE_SECRET` replaces the TypeScript of the default secret of the account of an `apiPath`.

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

Both fields are required. The answer is `{ "success": true, "statusCode": 200, "data": true }`.

## Errors

| Status | Message | When |
|---|---|---|
| `401` | `Unauthorized. Invalid communication token.` | The token is not the one of the settings. |
| `403` | `Operate API Maker using API feature is not enabled.` | The setting is off. |
| `403` | `Please set communication token from root user settings.` | The setting is on, without a token. |
| `404` | `User not found with apiPath : '<apiPath>'` | `UPDATE_ADMIN_USER` or `UPDATE_SECRET` for an `apiPath` no active account has. `Default secret not found in the system` : the account has no default secret. |
| `400` | `User already exists with apiPath : '<apiPath>'` | `CREATE_ADMIN_USER` for an `apiPath` an active account has. |

The answer of an error is the usual envelope : `{ "success": false, "statusCode": 401, "errors": [ { "message": "…" } ] }`.

## Related

- [API Maker configuration](https://docs.apimaker.dev/v4/docs/am-resources/api-maker-configurations.html) · [Secret Management](https://docs.apimaker.dev/v4/docs/secrets/secrets.html) · [Git integration](https://docs.apimaker.dev/v4/docs/Git/git.html)