FluxArk Management API Documentation

Connecting

  • Use the API Key created from the Web panel Settings -> Management API keys menu
  • The URI is /api/ along with the desired action
  • Use POST to send the JSON
  • A JSON object is required even if there are no input fields, so DONT send empty POST requests
FLUXARK_API_KEY='1vwAFfL3T42bhLJA52rqZEDFfgJLZXyuR'
curl https://localhost/api/servers/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $FLUXARK_API_KEY" \
  -d '{
    "name": "test_server",
    "ip_addr": "127.0.0.1"...
  }'

Missing access

The server will respond with HTTP error 403 if you don't have the permisions to do the action

Result on error

{
  "messages": [
    "Duplicate server name"
  ],
  "status": "ERROR",
  "time": 1726505912
}
  • status string OK|ERROR In case of error the value will be ERROR
  • mesages array[string] Collection of the errors
  • time int unix timestamp The Unix timestamp that the event occurred at

Remote Servers

The base path of the API for managing the servers is /api/servers/ You must have the permisson for Servers within your API key

Fields

These fields are used on server list/create/update

Mutable fields

  • name string UNIQUE Required. Name of the server. Later this can be used as a remote host destination when connecting through SSH
  • ip_addr string Required FQDN name or the IP address of the remote server
  • active int 1|0 = 1 Server is active
  • is_jump int 1|0 = 0 Indicator that the server can act as a Jump Server
  • is_cron int 1|0 = 0 Indicator that the server can act as a target for the SSH Cron jobs
  • is_api int 1|0 = 0 Indicator that the server can act as a target for the SSH API
  • port int 1-65535 = 22 The default SSH port thats used when connecting to any remote user on that server
  • groups array[string] List of the server group names. The groups will be created if missing

Read only fields

  • id int The DB record ID. Returned on create/update
  • created string datetime MySQL datetime format 'YYYY-MM-DD HH:MI:SS'. Returned only on list
  • users array[object] List of the SSH remote users. Returned only on list. The users can be modified in a separate API call

List servers

  • URI

    /api/servers/list

  • Method

    GET

Here you can get all the servers along with their groups and SSH users. Example output:

[
  {
    "is_api": 0,
    "is_jump": 1,
    "ip_addr": "127.0.0.1",
    "port": 22,
    "name": "test API",
    "groups": [
        "localhost"
    ],
    "active": 1,
    "is_cron": 0,
    "id": 10,
    "created": "2024-06-24 15:17:09",
    "users": [
      {
        "id": 11,
        "updated": null,
        "ssh_key": "Example working key with password",
        "created": "2024-07-06 12:34:56",
        "auth_method": "key-pass",
        "active": 1,
        "default_user": 1,
        "username": "demayl",
        "has_password": 1,
        "port": 22
      }
    ]
  },
]

Create

  • URI

    /api/servers/create

  • Method

    POST

Example input:

{
  "groups": [
    "api_test"
  ],
  "name": "server1",
  "active": true,
  "ip_addr": "server-gw.localhost.com",
  "is_api": false,
  "port": 22,
  "is_jump": true,
  "is_api": false,
  "is_cron": false
}

Output on success:

{
  "id": 43,
  "status": "OK"
}

Update

  • URI

    /api/servers/$SERVER-ID

  • Method

    POST

Use empty parameter groups if you want to delete the server groups associated with the server.
Example with URI /api/servers/43

{
  "groups": [
    "api_test2"
  ],
  "name": "server2",
  "active": true,
  "ip_addr": "server-gw.localhost.com",
  "is_api": false,
  "port": 22,
  "is_jump": true,
  "is_api": false,
  "is_cron": false
}

Following the create example, here we change the associated group to api_test2 and the name to server2.
Note that on update all the fields must be passed as parameters. For example if you post an empty group, the server groups will be deleted.
And all the other not required fields will be set to their defaults.

Delete

  • URI

    /api/servers/delete/$SERVER-ID

  • Method

    DELETE

Result success:

{
  "id": 45,
  "status": "OK"
}

Result error:

{
  "time": 1726507701,
  "status": "ERROR",
  "messages": [
    "Missing server"
  ]
}

List Remote SSH User

  • URI

    /api/servers/$SERVER-ID/users

  • Method

    GET

You need to have an existing Server in order to list it's users

[
  {
    "username": "root",
    "default_user": 1,
    "port": 22,
    "id": 14,
    "created": "2024-09-01 17:32:12",
    "server_id": 11,
    "auth_method": "password",
    "ssh_key": "",
    "has_password": 1,
    "active": 1
  }
]

Create Remote SSH User

  • URI

    /api/servers/$SERVER-ID/users

  • Method

    POST

You need to have an existing Server in order to create users

{
    "name": 'test_user',
    "ip_addr": '127.0.0.1',
    "active": true,
    "port": 22,
    "is_api": 0,
    "is_jump": 0,
    "groups": ["api_test", "api_test2"],
}

Result 

{
    "id": 1,
    "status": "OK"
}

Update existing Remote SSH User

  • URI

    /api/servers/$SERVER-ID/users/$USER-ID

  • Method

    POST

By using this endpoint you can update your existing SSH users of some server. Only provided fields will be updated in the user account.
We will use the already created account with ID 1 and Server ID 46 to deactivate the account :

/api/servers/46/users/1

Request:

{
    "active": false
}

Result:

{
    "status": "OK",
    "id": 1
}

Deleting a Remote SSH User

  • URI

    /api/servers/$SERVER-ID/users/$USER-ID

  • Method

    DELETE

Result:

{
    "status": "OK",
    "id": 1
}

Users

The base path for managing the users is /api/users/
Note that you must have the permission in order to access this API

Fields

These fields are used on user list/create/update. The required fields are only for user creation. When POSTing you can use a boolean value for the fields that are int 1|0

Mutable fields

  • username string UNIQUE Required. The username must follow the unix standarts - no special characters and maximum 32 chars long. It cannot be cnanged afterwards.
  • email string UNIQUE Required. Email of the user. It must be unique.
  • password string Required The password must pass the "strength" check
  • full_name string Required Name of the user
  • auth_type string Required On user login it picks whenever to use only a password, SSH key or both at the same time. Values:
    • password Requires only the password on user login, even with a ssh-key set
    • password-key Requires both a password and an SSH key
    • key Requires only an SSH key
  • password_type string Required Decides if the user password will require 2FA
    • password Requires only the standart password on login
    • token Requires only 2FA token as a password
    • password-token Requires only 2FA token + password. When using you will enter first the password and then the token $PASSWORD$TOKEN
  • ssh_key string The public SSH key if needed for authorization
  • active int 1|0 When disabled the user won't be able to log in anymore.
  • server_admin int 1|0 When enabled the user will connect directly to the jump server and won't be able to use the Jump server service!
  • comment string Only for reference information
  • ip_allow_list string List of IP addresses only from which the user can connect from. 192.168.0.100,127.0.0.1/24
  • groups array[string] List of the user group names. The groups must exist

Read only fields

  • id int The DB record ID. Returned on create/update
  • created string datetime MySQL datetime format 'YYYY-MM-DD HH:MI:SS'. Returned only on list

List

  • URI

    /api/users/list

  • Method

    GET

Result:

[
  {
    "full_name": "testing",
    "active": 1,
    "login_tries": 5,
    "ip_allow_list": "192.168.0.1, 127.0.0.1",
    "id": 14,
    "username": "info",
    "created": "2024-07-16 16:08:49",
    "groups": [
      "test",
      "fluxark.com"
    ],
    "password_type": "password",
    "email": "testing@fluxark.com",
    "auth_type": "key",
    "server_admin": null,
    "last_pass_update_date": "2024-09-04 15:11:59",
    "password_expire_date": "2024-12-03 15:11:59"
  },
  {
    "groups": [
    ],
    "ip_allow_list": "",
    "server_admin": 1,
    "full_name": "local admin",
    "auth_type": "key",
    "password_type": "password",
    "id": 15,
    "login_tries": 4,
    "last_pass_update_date": "2024-09-04 15:11:59",
    "password_expire_date": "2024-12-03 15:11:59",
    "username": "badmin",
    "active": 1,
    "email": "badmin@fluxark.com",
    "created": "2024-08-03 10:10:17"
  },
]

Create

  • URI

    /api/users/create

  • Method

    POST

You can read about the user fields before using this endpoint.
Here is an example of creating user hapi with password 1234 and part of the group fluxark.com.
In this case after creation the user will have access to all associated servers with the group fluxark.com using the password 1234. Here how the connection will look using the example server and user that we already created and fluxark.com as an example installed server:
ssh test_user@server2@hapi@fluxark.com

{
  "email": "hapi@fluxark.com",
  "password": "1234",
  "ip_allow_list": "127.0.0.1",
  "active": true,
  "username": "hapi",
  "auth_type": "password",
  "full_name": "hapi test",
  "groups": [
    "fluxark.com"
  ],
  "password_type": "password"
}

Result:

{
    "status": "OK",
    "id": 1
}

Update

  • URI

    /api/users/$USER-ID

  • Method

    POST

Here we will change the password and associate with a second group called "administrators"

{
  "password": "12345",
  "groups": [
    "administrators",
    "fluxark.com"
  ],
}

Result:

{
    "status": "OK",
    "id": 1
}

Delete

  • URI

    /api/users/$USER-ID

  • Method

    DELETE

Note that deleting a user will remove it's home directory and all SSH session log files! It's better only to deactivate him in order to retain the SSH session logs.

Result:

{
    "status": "OK",
    "id": 1
}

Examples

Deactivate

{
  "active": false
}

Change password

{
  "password": "some new password"
}

Remove associated groups

{
  "groups": []
}

Add a public SSH KEY

{
  "ssh_key": "ssh-rsa AAA..."
}

Access list

From this endpoints you can control the access to a single remote user. After adding or deleting a rule, the user will have their access granted/revoked!

Fields

  • expire_time string datetime After this UTC date time the ACL won't be valid.
  • expire_days int Based on them the expire_time field will be calculated. Used when creating a rule.
  • user_server_id int ID of the remote SSH user. You can see them here
  • created string datetime UTC creation date time
  • server_id int ID of the remote SSH server. Readonly
  • acl_id int ID of the rule. Can be used for deleting later

List

  • URI

    /api/users/$USER-ID/acl

  • Method

    GET

[
  {
    "expire_time": "",
    "user_server_id": 14,
    "created": "2024-09-01 17:33:02",
    "server_id": 11,
    "acl_id": 42
  },
  {
    "acl_id": 44,
    "server_id": 5,
    "user_server_id": 17,
    "expire_time": "2024-09-17 12:34:45",
    "created": "2024-09-14 12:34:45"
  }
]

Add rule

  • URI

    /api/users/$USER-ID/acl

  • Method

    POST

Add without any expire time

{
  "user_server_id": 1,
}

Add using expire time 3 days later from now.

{
  "user_server_id": 1,
  "expire_days": 3
}

Add using expire time at exact datetime.

{
  "user_server_id": 1,
  "expire_time": "2025-09-24 14:31:42"
}

Delete rule

  • URI

    /api/users/$USER-ID/acl/$ACL_ID

  • Method

    DELETE

Result:

{
  "status": "OK"
}

User Groups

With this endpoints you can control the access of a user group to a group of servers. Note that you must have assigned already a group to the servers that you want to grant access to.
If you want to give access to a single remote SSH user, you can use the users ACL where you can provide access to a single remote SSH user.

Fields

  • id int ID of the user group
  • name string Name of the user group
  • expire_time string datetime Expire date time of the rule
  • created string datetime When was the rule created
  • username string remote SSH username, can be comma separated list an asterisk (*) or empty
    • * The group has access to every remote SSH user
    • user1,user2 The group has access only to these 2 remote SSH users
    • empty Every user from the group will have access only to the same remote usernames as his
  • server_groups array[object]
    • id int ID of the server group. Used later when removing a server group rule from a user group
    • name string name of the server group. See the Servers documentation for more information

List

  • URI

    /api/users/groups

  • Method

    GET

[
  {
    "id": 7,
    "expire_time": "",
    "name": "asd",
    "created": "2024-08-31 12:48:04",
    "server_groups": [
      {
        "id": 17,
        "name": "testing"
      }
    ]
  },
  {
    "name": "wtf",
    "id": 8,
    "created": "2024-08-31 12:48:04",
    "expire_time": "",
    "server_groups": []
  },
  {
    "server_groups": [
      {
        "id": 31,
        "name": "api"
      },
      {
        "name": "passwd",
        "id": 33
      }
    ],
    "id": 2,
    "created": "2024-08-31 12:48:04",
    "expire_time": "2025-08-31 12:48:04",
    "name": "test"
  }
]

Create

  • URI

    /api/users/groups

  • Method

    POST

Request:

{
  "name": "new_group"
}

Response:

{
  "status": "OK",
  "id": 8
}

Delete

  • URI

    /api/users/groups/$ID

  • Method
  • DELETE

Add server group

  • URI

    /api/users/groups/$ID/server_groups

  • Method

    POST

  • group_name string REQUIRED

  • expire_time string optional
  • username string The remote ssh username. Here we have the following options:
    • * Using the asterisk as a username, the group will have access to every remote ssh user
    • empty Then every group user will have only access to the user with the same username. For example the user admin will only have access to the remove user admin
    • username All the users in this group will have access only to this specific username. For example using root the users will have only access to the remote root account
    • user1,user2 All the users in this group will have access only to this list of remote users. Note that when the remote user is not defined in the server users, the default * remote user will be used

Request:

{
  "group_name": "existing_server_group_name",
  "expire_time": "2024-08-31 12:48:04",
  "username": "root"
}

Result:

{
  "status": "OK",
  "id": 5
}

Delete server group

  • URI

    /api/users/groups/$ID/server_groups/$SERVER_GROUP_NAME

  • Method

    DELETE

Request

/api/users/groups/3/server_group/existing_server_group_name

Response:

{
  "status": "OK",
  "id": 14
}

Cron

By using this API endpoint you can create,modify, delete and access the output of the online SSH cron jobs

API

By using this API endpoint you can manage your SSH API commands