This page View Markdown Open in ChatGPT Open in Claude

Operate API Maker using API¶

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¶

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

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¶

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.

{
    "token": "aBcDe_FgHiJ_KlMnO_PqRsT_UvWxY_ZaBcD_EfGhI_JkLmN_OpQrS",
    "operation": "CREATE_ADMIN_USER",
    "payload": {
        "user": {
            "name": "John Doe",
            "email": "[email protected]",
            "password": "securePassword123",
            "apiPath": "john_doe",
            "gitUrlWithCredentials": "https://username:[email protected]/username/repo.git",
            "gitCommitUserEmail": "[email protected]",
            "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.

Answer

{
    "success": true,
    "statusCode": 200,
    "data": {
        "userResponse": {
            "guid": "01KP2MCKX5DNBGM7RCAASM3BMQ",
            "name": "John Doe",
            "email": "[email protected]",
            "apiPath": "john_doe",
            "gitCommitUserEmail": "[email protected]",
            "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 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.

{
    "token": "aBcDe_FgHiJ_KlMnO_PqRsT_UvWxY_ZaBcD_EfGhI_JkLmN_OpQrS",
    "operation": "UPDATE_ADMIN_USER",
    "payload": {
        "find": { "apiPath": "john_doe" },
        "updateData": {
            "name": "John Doe",
            "email": "[email protected]",
            "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.

{
    "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.

{
    "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": "…" } ] }.

API Maker configuration · Secret Management · Git integration