HF PanelDocsv1.0.0

API: MongoDB

Create and delete MongoDB databases and users, grant roles and set remote access through the token API.

These endpoints manage one hosting account's MongoDB databases, their users and remote access. With a customer's token they work on the token's own account. With an administrator's or reseller's token, add ?account=<username>. Every change needs a Read & change token. A customer's token gets 403 "This feature is not part of your hosting plan." when the plan does not include MongoDB.

bash
A=https://api.yourdomain.com:2087/v1
H="Authorization: Bearer hf_xxx"

Names

Database and user names always start with the account's username and an underscore, for example sarahbakes_app. In paths and bodies you can give the full name (sarahbakes_app) or only the part after the underscore (app).

The part you choose is 1–15 lower-case letters, numbers or _. A few names are reserved; you then get 422 "That name is reserved. Choose another."

GET /v1/mongo

The account's MongoDB databases, users and remote access. Who: per account; any token.

bash
curl -s -H "$H" "$A/mongo?account=sarahbakes"
json
{
    "ok": true,
    "data": {
        "ready": true,
        "host": "panel.yourdomain.com",
        "port": 27017,
        "limit": 5,
        "used": 1,
        "databases": [
            {
                "name": "sarahbakes_app",
                "size_bytes": 81920,
                "collections": 3,
                "users": [
                    {
                        "user": "sarahbakes_app",
                        "role": "readWrite"
                    }
                ],
                "created_at": "2026-10-02 14:11:09"
            }
        ],
        "users": [
            {
                "name": "sarahbakes_app",
                "databases": [
                    {
                        "database": "sarahbakes_app",
                        "role": "readWrite"
                    }
                ],
                "created_at": "2026-10-02 14:11:09"
            }
        ],
        "remote_ips": [
            "203.0.113.7"
        ]
    }
}
Field What it is
ready whether MongoDB answers on the account's server
host, port where to connect from outside (with TLS)
limit how many MongoDB databases the package allows: null = no limit, 0 = none
used how many the account has
size_bytes, collections the database's size and number of collections; null when not known
remote_ips the addresses allowed to connect from outside; empty = remote access is off

Connection strings

From Connection string
the server itself (websites, cron jobs) mongodb://<user>:<password>@127.0.0.1:27017/<database>?authSource=<database>&tls=false
an allowed address outside mongodb://<user>:<password>@<host>:27017/<database>?authSource=<database>&tls=true

POST /v1/mongo

Creates a database. By default it also creates a user of the same name with the readWrite role and a random password. Who: per account, Read & change token. Answers 201.

Field Required What it does
name yes the database's name, full or the part after <username>_
user no false (or 0) creates the database only, without a user
bash
curl -s -H "$H" -H 'Content-Type: application/json' "$A/mongo?account=sarahbakes" \
     -d '{"name":"app"}'
json
{
    "ok": true,
    "data": {
        "database": "sarahbakes_app",
        "user": "sarahbakes_app",
        "password": "Xb3rT9qLm2Wk7Vc4Nz8P",
        "uri": "mongodb://sarahbakes_app:Xb3rT9qLm2Wk7Vc4Nz8P@127.0.0.1:27017/sarahbakes_app?authSource=sarahbakes_app&tls=false"
    }
}

The password is shown only in this answer. With "user": false, data holds only database.

Status error
422 That database already exists.
422 A database user with that name already exists — create the database only, then add a user.
422 Your package does not include MongoDB databases.
422 MongoDB database limit reached for this package.

DELETE /v1/mongo/{database}

Deletes the database and all its data. Its users stay. Who: per account, Read & change token.

bash
curl -s -H "$H" -X DELETE "$A/mongo/app?account=sarahbakes"
json
{
    "ok": true,
    "data": {
        "deleted": "sarahbakes_app"
    }
}

An unknown database answers 422 "Database not found."

POST /v1/mongo/{database}/grant

Lets a user use a database. Who: per account, Read & change token.

Field Required What it does
user yes the user's name, full or short
role no readWrite (the default) or read
bash
curl -s -H "$H" -H 'Content-Type: application/json' "$A/mongo/app/grant?account=sarahbakes" \
     -d '{"user":"reports","role":"read"}'
json
{
    "ok": true,
    "data": {
        "database": "sarahbakes_app",
        "user": "sarahbakes_reports",
        "role": "read"
    }
}

Another role answers 422 "Role: readWrite or read." An unknown user answers 422 "User not found."

POST /v1/mongo/{database}/revoke

Takes a user's role on a database away. Who: per account, Read & change token.

Field Required What it does
user yes the user's name, full or short
bash
curl -s -H "$H" -H 'Content-Type: application/json' "$A/mongo/app/revoke?account=sarahbakes" \
     -d '{"user":"reports"}'
json
{
    "ok": true,
    "data": {
        "database": "sarahbakes_app",
        "user": "sarahbakes_reports",
        "role": null
    }
}

POST /v1/mongo/users

Creates a database user. Give it access with grant. Who: per account, Read & change token. Answers 201.

Field Required What it does
name yes the user's name, full or the part after <username>_
password no 8–128 characters, without quotes ('), backslashes or control characters. Without it, a random one is made
bash
curl -s -H "$H" -H 'Content-Type: application/json' "$A/mongo/users?account=sarahbakes" \
     -d '{"name":"reports"}'
json
{
    "ok": true,
    "data": {
        "user": "sarahbakes_reports",
        "password": "Lq8Zr2Kv6Tm9Wb3Xc7Nd"
    }
}

An existing name answers 422 "That user already exists."

POST /v1/mongo/users/{user}/password

Sets a new password for a user. PUT works too. Who: per account, Read & change token.

Field Required What it does
password no the new password, with the same rules as above. Without it, a random one is made
bash
curl -s -H "$H" -X POST "$A/mongo/users/reports/password?account=sarahbakes"
json
{
    "ok": true,
    "data": {
        "user": "sarahbakes_reports",
        "password": "Rk4Wn8Tb2Lq6Zv9Xm3Pc"
    }
}

DELETE /v1/mongo/users/{user}

Deletes a database user. Who: per account, Read & change token.

bash
curl -s -H "$H" -X DELETE "$A/mongo/users/reports?account=sarahbakes"
json
{
    "ok": true,
    "data": {
        "deleted": "sarahbakes_reports"
    }
}

POST /v1/mongo/remote

Sets the IP addresses that may connect to the account's MongoDB databases from outside, on port 27017 with TLS. PUT works too. Who: per account, Read & change token.

Field Required What it does
ips yes a list of addresses, or one text with spaces or commas between them. Up to 20. IPv4 addresses may have a /prefix. An empty list switches remote access off
bash
curl -s -H "$H" -H 'Content-Type: application/json' "$A/mongo/remote?account=sarahbakes" \
     -d '{"ips":["203.0.113.7","198.51.100.0/24"]}'
json
{
    "ok": true,
    "data": {
        "remote_ips": [
            "203.0.113.7",
            "198.51.100.0/24"
        ]
    }
}
Status error
422 Not a valid IP address: …
422 Up to 20 addresses.