Login/Register
Installatron Server
API Documentation
⌂

Create User

POST /users

Create an Installatron Server user.

Parameters


API

/users
API endpoint.

{id} is the username to create.
POST
Method.

Required parameters

id
string
Username of the user to create.

Optional parameters

email
string
The primary email address for the user. This value can also be defined per website.

default is the existing value or an empty string for new users
language
enum
The language the user interface should display in. For example,
en
for English or
nl
for Dutch. See: Available Installatron Translations.

default is the default language or
en
(English)
package
string
The webhosting package this user belongs to. Can be any valid string value. Packages are used by Installatron Groups to provide different configurations to different users.

default is the existing value or an empty string for new users
parent
string
The name of the account that owns this user's account.

default is the main administrative user so this argument only needs to be added if this user is owned by a reseller account.
suspended
boolean
false
= The user is not suspended.
true
= The user is suspended.

default is
false
type
enum
user
to grant this user access to Installatron's user-level GUI.

reseller
to grant this user access to Installatron's administrative GUI; if the {id} in the command matches the admin= value in /usr/local/installatron/etc/settings.ini then the session will grant access to Installatron's main administrator GUI, otherwise it will be created for the reseller GUI.

default is
user

Optional websites definition

The
websites[]
parameter informs Installatron Server about the user's domains.

It's recommended that you include the websites definition when creating a user, and that you edit this definition any time the user's domains situation changes.

The two most important parameters in the websites definition are the path and vhosts which, in combination, tell Installatron Server where to locate the files of a domain. The path locates the user's 'home folder'--and this can be a path on the local system or a URL (including login information) to a remote location via any supported protocol--and then vhosts shows the path from that home folder to each of the domain docroots ('home directories').

Those parameters, and the others, are described in more detail below.
websites[]


↳
path
string
(This argument is required unless the instructions outlined in Path On Demand are followed to define paths only when they are required by Installatron.)

The path or URI to the home directory of this domain (without a trailing directory separator).

Important notes for URI values:
  • The entire URI is AES encrypted in Installatron Server's database.
  • To ensure correct URI syntax the username and password values should be URL-encoded.
  • SSH**
  • FTP
  • FTPS
  • SFTP**

** Both password and public key-based authentication are supported for the SSH and SFTP filesystem protocols; to authenticate by public key, substitute the contents of the key for the password.

Reminder: URI's that contain special characters within the username and password values must be URL-encoded per the specification RFC 3986. For example, a username of
user@installatron.com
should be provided as
user%40installatron.com
.

Examples:
  • /home/USERNAME
  • /var/www/vhosts/DOMAIN
  • c:\inetpub\vhosts\DOMAIN
  • sftp://".urlencode('USER').":".urlencode('PASS')."@SERVER
  • sftp://".urlencode('USER').":".urlencode('PASS')."@SERVER/home
  • ssh://".urlencode('USER').":".urlencode('PASS')."@SERVER
↳
vhosts
associative array
Example 1:
  • 'http://mysite.com' => 'httpdocs',
    'http://www.mysite.com' => 'httpdocs'

Example 2:
  • 'http://mysite.com' => 'public_html',
    'http://www.mysite.com' => 'public_html',
    'https://mysite.com' => 'private_html',
    'https://www.mysite.com' => 'private_html'

Example 3:
  • 'http://mysite.com' => 'public_html/mysite.com',
    'http://www.mysite.com' => 'public_html/mysite.com',
    'https://mysite.com' => 'public_html/mysite.com',
    'https://www.mysite.com' => 'public_html/mysite.com'
↳
databases[]


↳
type
string
Must be a value of
mysql
at this time.

default is
mysql
↳
host
string
Hostname/IP of this database's server.
(eg.
localhost
)
(eg.
mysql.website.com:3308
)

value is required
↳
name
string
Name of this database.
(eg.
useraccountname_wp1
)

value is required
↳
user
string
Name of this database-user.
(eg.
useraccountname_wp1
)

value is required
↳
pass
string
Password for this database-user and database pair.
(eg.
1a.2b3c4d5e%6f7g8h)9i0
)

Note that the database-user should have full privileged access to the database.

value is required
↳
gid
int
The filesystem POSIX UID that files should be created as for this website.
(eg.
1234
)

Note: Required when path is a local filesystem or NFS share. Otherwise omitted.
↳
uid
int
The filesystem POSIX GID that files should be created as for this website.
(eg.
1234
)

Note: Required when path is a local filesystem or NFS share. Otherwise omitted.
↳
label
string
A value that uniquely identifies this website.
(eg.
938c2cc0dcc05f2b68c4287040cfcf71
)
↳
language
enum
This website's default language. This is the language text strings and error messages will display in for requests involving this website.
(eg.
nl
)

See: Available Installatron Translations.

default is the user's language value, the 'default language', or
en
↳
server
string
A unique value to describe the physical web server, such as a UUID, hostname or IP address. This identifier is used for load balancing and task throttling to ensure no single server becomes overloaded during Installatron Server's normal operations.

default is the
path
host when path is defined
default is the
username
when no path is defined
↳
suspended
boolean
false
= This website is not suspended.
true
= This website is suspended.

default is the website is not suspended
↳
vhost_ip
string
The IP address each domain listed in vhosts should resolve to, enabling Installatron Server to install to vhosts that might not resolve through DNS.
(eg.
123.123.123.123
)

default is this parameter is unused

Special parameters

dryrun
enum
Perform a test run of this API call: run the tests, check connections to the database server and remote locations, but don't actually perform this task itself. This is just a test-run to make sure that when it is run for real that there is nothing to stop it from working.
  • none
    = No dry run.
  • all
    = Check all input values and test all connections.
  • input
    = Check only the input values.


default is
none

Response


Response

status
int
HTTP status code describing the result of the request.

200
for Success.
All other numbers represent errors which are described in the errcode output below.
result
boolean
true
= Success.
false
= Failure.
errcode
string
status code 200
complete_dryrun
dryrun was enabled and finished without error.
status code 403
invalid_api_key
The server's Installatron Server Key is invalid.
invalid_argument_id
The {id} provided is not valid or does not exist in the list.
message
string
Message describing the result of the request. Do not rely on this to determine the success or failure of the request.
data


↳
id
string
Username of this user.
↳
parent
string
Reseller or admin account that owns this user's account. (ie. the account that created this user) This will be either the main administrative user of the server or a reseller who is in turn owned by the main administrative account of the server.
↳
type
enum
user
for an account with no Installatron administrative access.

reseller
for an account with Installatron administrative access. If the
user
matches the admin= value in /usr/local/installatron/etc/settings.ini then they will be have full administrative access to Installatron, otherwise they will receive reseller administrative access.
↳
suspended
boolean
true
= The account is suspended.
false
= The account is not suspended.
↳
locale
enum
Language this user views Installatron in
(eg.
en
,
nl
).

See: Available Installatron Translations for a full list of languages that Installatron is available in.
↳
email
string
User's email address.
↳
websites[]


↳
path
string
The path or URI to the home directory of this domain (without a trailing directory separator).

Important notes for URI values:
  • The entire URI is AES encrypted in Installatron Server's database.
  • To ensure correct URI syntax the username and password values should be URL-encoded.
  • The host portion of the URI is used to distinguish between web servers. It's considered best practice to use a web server-referencing hostname (eg., server123.host.net) or an IP address for the host portion of the URI. If this is not possible, make sure to include the server argument as documented below.

Supported protocols:
  • The local filesystem (including NFS shares)
  • SSH**
  • FTP
  • FTPS
  • SFTP**

** Both password and public key-based authentication are supported for the SSH and SFTP filesystem protocols; to authenticate by public key, substitute the contents of the key for the password.

Reminder: URI's that contain special characters within the username and password values must be URL-encoded per the specification RFC 3986. For example, a username of
user@installatron.com
should be provided as
user%40installatron.com
.

Examples:
  • /home/USERNAME
  • /var/www/vhosts/DOMAIN
  • c:\inetpub\vhosts\DOMAIN
  • sftp://".urlencode('USER').":".urlencode('PASS')."@SERVER
  • sftp://".urlencode('USER').":".urlencode('PASS')."@SERVER/home
  • ssh://".urlencode('USER').":".urlencode('PASS')."@SERVER
↳
vhosts
associative array
Example 1:
  • 'http://mysite.com' => 'httpdocs',
    'http://www.mysite.com' => 'httpdocs'

Example 2:
  • 'http://mysite.com' => 'public_html',
    'http://www.mysite.com' => 'public_html',
    'https://mysite.com' => 'private_html',
    'https://www.mysite.com' => 'private_html'

Example 3:
  • 'http://mysite.com' => 'public_html/mysite.com',
    'http://www.mysite.com' => 'public_html/mysite.com',
    'https://mysite.com' => 'public_html/mysite.com',
    'https://www.mysite.com' => 'public_html/mysite.com'
↳
databases[]


↳
type
enum
Must be a value of
mysql
at this time.
↳
host
string
Hostname/IP of this database's server.
↳
name
string
Name of this database.
↳
user
string
Name of this database-user.
↳
pass
string
Password for this database-user and database pair.

Note that the database-user should have full privileged access to the database.
↳
gid
int
The filesystem POSIX UID that files and folders will be created as for this website.
↳
uid
int
The filesystem POSIX GID that files and folders will be created as for this website.
↳
label
string
A value that uniquely identifies this website.
↳
language
enum
This website's default language. This is the language text strings and error messages will display in for requests involving this website. For example,
en
for English or
nl
for Dutch. See: Available Installatron Languages.
↳
server
string
The host portion of the path URI is used to distinguish between web servers by default. If the path is not defined, and is instead determined On Demand, then the default will be NULL. If for whatever reason this NULL value doesn't correctly distinguish web servers then give this parameter a unique value for each web server.
↳
suspended
boolean
false
= This website is not suspended.
true
= This website is suspended.
↳
vhost_ip
string
The IP address each domain listed in vhosts should resolve to, enabling Installatron Server to install to vhosts that might not resolve through DNS.

Full Examples

Example: Create an Installatron Server user named "useraccountname" and configure its websites

Method: curl
Installatron Product: Installatron Server 
curl -X POST https://{SERVER_IP}/users \
    -H 'X-API-KEY: {the key= or key2= value from /usr/local/installatron/etc/settings.ini}' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '
        {
            "id": "useraccountname",
            "websites": [
                {
                    "path": "sftp://exampleftpuser:exampleftppassword@website.com",
                    "label": "website.com",
                    "server": "website.com",
                    "reseller": "root",
                    "vhosts": {
                        "http://website.com": "httpdocs",
                        "http://www.website.com": "httpdocs"
                    }
                },
                {
                    "path": "sftp://exampleftpuser:exampleftppassword@website.com/subdomain",
                    "label": "subdomain.website.com",
                    "email": "user@mail.com",
                    "vhosts": {
                        "http://subdomain.website.com": "httpdocs/subdomain",
                        "https://subdomain.website.com": "httpdocs/subdomain"
                    }
                }
            ]
        }
       '
Response: json
{
    "result": true,
    "status": 200,
    "errcode": null,
    "errfield": null,
    "message": "The task is complete.\n"
    "data": {
        "id": "useraccountname",
        "parent": "root",
        "type": "user",
        "suspended": false,
        "locale": "en",
        "email": "address@website.com",
        "websites": [
            {
                "path": "sftp://exampleftpuser:exampleftppassword@website.com",
                "label": "website.com",
                "server": "website.com",
                "parent": "root",
                "databases": [
                    {
                        "type": "mysql",
                        "host": "localhost",
                        "user": "useraccountname_mytestdb1",
                        "name": "useraccountname_mytestdb1",
                        "pass": "exampledbpassword1"
                    }
                ],
                "vhosts": {
                    "http://website.com": "public_html"
                }
            },
            {
                "path": "sftp://exampleftpuser:exampleftppassword@website.com/subdomain",
                "server": "website.com",
                "label": "subdomain.website.com",
                "parent": "root",
                "databases": [
                    {
                        "type": "mysql",
                        "host": "123.123.123.123:3307",
                        "user": "useraccountname_mytestdb2",
                        "name": "useraccountname_mytestdb2",
                        "pass": "exampledbpassword2"
                    }
                ],
                "vhosts": {
                    "http://subdomain.website.com": "public_html/subdomain",
                    "https://subdomain.website.com": "public_html/subdomain"
                }
            }
        ]
    }
}

Example: Set a package for an Installatron Server user

Method: curl
Installatron Product: Installatron Server 
curl -X POST https://{SERVER_IP}/users \
    -H 'X-API-KEY: {the key= or key2= value from /usr/local/installatron/etc/settings.ini}' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '
        {
            "id": "useraccountname",
            "type": "reseller"
        }
       '
Response: json
{
    "result": true,
    "status": 200,
    "errcode": null,
    "errfield": null,
    "message": "The task is complete.\n"
    "data": {
        "id": "useraccountname",
        "parent": "root",
        "type": "user",
        "suspended": false,
        "locale": "en",
        "email": "address@website.com",
        "websites": [
            {
                "path": "sftp://exampleftpuser:exampleftppassword@website.com",
                "label": "website.com",
                "server": "website.com",
                "parent": "root",
                "databases": [
                    {
                        "type": "mysql",
                        "host": "localhost",
                        "user": "useraccountname_mytestdb1",
                        "name": "useraccountname_mytestdb1",
                        "pass": "exampledbpassword1"
                    }
                ],
                "vhosts": {
                    "http://website.com": "public_html"
                }
            },
            {
                "path": "sftp://exampleftpuser:exampleftppassword@website.com/subdomain",
                "server": "website.com",
                "label": "subdomain.website.com",
                "parent": "root",
                "databases": [
                    {
                        "type": "mysql",
                        "host": "123.123.123.123:3307",
                        "user": "useraccountname_mytestdb2",
                        "name": "useraccountname_mytestdb2",
                        "pass": "exampledbpassword2"
                    }
                ],
                "vhosts": {
                    "http://subdomain.website.com": "public_html/subdomain",
                    "https://subdomain.website.com": "public_html/subdomain"
                }
            }
        ]
    }
}


© 2004 - 2025 Installatron LLC. All rights reserved. Privacy Policy.