s3.php¶

S3 storage management module: creating and deleting accounts, managing buckets and files, retrieving usage statistics, managing billing plans and billing.

API Methods¶

Method	Action	Description
`create_account`	create S3 account	Creates a new S3 account for the client, links a billing plan, creates a bucket, and places an order in billing.
`create_bucket`	create S3 bucket	Creates a new bucket in S3 storage for the specified user. Requires a valid s3uid of the current client.
`create_order`	create S3 storage order	Creates a new S3 storage order for the client. Validates the billing plan, checks free account limits or credits, creates an S3 user, bucket, and billing service.
`delete_account`	delete S3 account	Completely deletes the user's S3 account. Requires specifying the client ID (for an administrator) or uses the current user's ID, as well as the s3uid of the target account.
`delete_bucket`	delete S3 bucket	Deletes the specified S3 bucket. Checks access rights and bucket ownership by the user.
`delete_file`	delete file	Deletes the specified file from the S3 bucket. Requires token validation and client access rights check.
`delete_payment_account`	cancel account payment	Initiates cancellation of a paid S3 account. Sets the cancellation date for the service associated with the specified s3uid.
`get_buckets`	get bucket list	Returns a list of buckets for the specified S3 account, including information on storage usage, quota, metrics, and access keys. Uses an asynchronous request via a task queue.
`get_buckets_rmq`	get bucket and metrics list via RMQ	Returns a list of S3 user buckets, information on storage usage, quota, traffic metrics, and access keys. Uses a message queue (RMQ) to retrieve current data.
`get_files`	get file list	Returns a list of files and folders in the specified S3 bucket with pagination and search support.
`get_users`	get S3 user list	Returns a list of S3 users with information on traffic, storage usage, and service status. Supports filtering by client ID, plan ID, email, billing, s3uid, bucket_name, storage_type. Sorting and pagination are available for administrators.
`history`	get billing plan change history	Returns the history of changes or events related to the specified S3 billing plan.
`list_plans`	get S3 plan list	Returns a list of available S3 billing plans. Hides inactive plans for clients (if no s3_test tag). For administrators, specifying id returns details of a specific plan.
`show_key`	get access key	Returns the decrypted access key (access_key or secret_key) for the specified S3 account.

s3/cancel_payment_account_deletion¶

Cancels a previously initiated procedure for deleting a paid S3 account. Requires token validation and access rights check.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `cancel_payment_account_deletion`
token	✅	string	User authorization token
s3uid	✅	string	Unique S3 user identifier (UID)
id	❌	int	Client ID (used by administrators to manage other accounts)

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=cancel_payment_account_deletion" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE"

Example of a successful response

{
"result": "OK",
"action": "cancel_payment_account_deletion",
"termination_date": "2024-12-31 23:59:59"
}

Failure response

``` { "code": -1, "message": "s3/cancel_payment_account_deletion: S3 account not found for this customer" }

```

s3/create_account¶

Creates a new S3 account for the client, links a billing plan, creates a bucket, and places an order in billing.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Action name: `create_account`
token	✅	string	User authorization token
plan_id	✅	int	S3 billing plan identifier
bucket_name	✅	string	Name of the bucket to be created (must be valid)
location	❌	string	Location code (default NL). Must be supported by the selected plan.

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=create_account" \
--data "token=HOSTKEY_TOKEN" \
--data "plan_id=VALUE" \
--data "bucket_name=VALUE"

Example of a successful response

{
"result": "OK",
"action": "create_account",
"s3uid": "7VT1xrnQbWSIQhoOrAngpLUL5reuFcXY"
}

Failure response

``` { "code": -1, "message": "s3/create_account: missing auth token", "details": { "possible_errors": [ "s3/create_account: customer not found", "s3/create_account: no plan_id found", "s3/create_account: invalid location", "s3/create_account: you have maximum 3 free S3 accounts", "s3/create_account: S3 account was created, but have error: ..." ] } }

```

s3/create_bucket¶

Creates a new bucket in S3 storage for the specified user. Requires a valid s3uid of the current client.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `create_bucket`
token	✅	string	User authorization token
s3uid	✅	string	Unique S3 user identifier (UID)
bucket_name	✅	string	Name of the bucket to be created

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=create_bucket" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE" \
--data "bucket_name=VALUE"

Example of a successful response

{
"result": "OK",
"action": "create_bucket",
"message": {
"status": "success",
"bucket_name": "my-new-bucket",
"location": "NL"
}
}

Failure response

{
"code": -1,
"message": "s3/create_bucket: S3 account not found for this customer",
"details": {
"s3uid": "invalid_uid"
}
}

s3/create_order¶

Creates a new S3 storage order for the client. Validates the billing plan, checks free account limits or credits, creates an S3 user, bucket, and billing service.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `create_order`
token	✅	string	User authorization token
plan_id	✅	int	S3 billing plan identifier
bucket_name	✅	string	Name of the bucket to be created (must be valid)
location	❌	string	Location code (default NL)

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=create_order" \
--data "token=HOSTKEY_TOKEN" \
--data "plan_id=VALUE" \
--data "bucket_name=VALUE"

Example of a successful response

{
"result": "OK",
"action": "create_order",
"s3uid": "7VT1xrnQbWSIQhoOrAngpLUL5reuFcXY"
}

Failure response

``` { "code": -1, "message": "s3/create_order: no plan_id found" }

```

s3/delete_account¶

Completely deletes the user's S3 account. Requires specifying the client ID (for an administrator) or uses the current user's ID, as well as the s3uid of the target account.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `delete_account`
token	✅	string	Authorization token
id	❌	int	Client ID (required for administrator, ignored for regular user)
s3uid	✅	string	Unique S3 user identifier (s3uid)

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=delete_account" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE"

Example of a successful response

{
"result": "OK",
"action": "delete_account",
"message": "Account deleted successfully"
}

Failure response

``` { "code": -1, "message": "S3 account not found for this customer" }

```

s3/delete_bucket¶

Deletes the specified S3 bucket. Checks access rights and bucket ownership by the user.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `delete_bucket`
token	✅	string	User authorization token
s3uid	✅	string	Unique S3 user identifier (UID)
bucket_name	✅	string	Name of the bucket to delete
id	❌	integer	Client ID (used by administrators to delete other users' buckets)

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=delete_bucket" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE" \
--data "bucket_name=VALUE"

Example of a successful response

{
"result": "OK",
"action": "delete_bucket",
"message": "Bucket deleted successfully"
}

Failure response

{
"code": -1,
"message": "s3/delete_bucket: bucket not found"
}

s3/delete_file¶

Deletes the specified file from the S3 bucket. Requires token validation and client access rights check.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `delete_file`
token	✅	string	User authorization token
s3uid	✅	string	Unique S3 user identifier (UID)
bucket_name	✅	string	Name of the bucket from which the file is deleted
filename	✅	string	File name (object key) to delete

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=delete_file" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE" \
--data "bucket_name=VALUE" \
--data "filename=VALUE"

Example of a successful response

{
"result": "OK",
"action": "delete_file",
"message": "string"
}

Failure response

``` { "code": -1, "message": "s3/delete_file: Delete S3 file error: {error_message}. Response: {response_data}." }

```

s3/delete_payment_account¶

Initiates cancellation of a paid S3 account. Sets the cancellation date for the service associated with the specified s3uid.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `delete_payment_account`
token	✅	string	User authorization token
s3uid	✅	string	Unique S3 user identifier
id	❌	int	Client ID (for administrators). If not specified, the ID from the token is used.

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=delete_payment_account" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE"

Example of a successful response

{
"result": "OK",
"action": "delete_payment_account",
"cancellation_date": "2024-12-31 23:59:59"
}

Failure response

{
"code": -1,
"message": "S3 account not found for this customer"
}

s3/get_buckets¶

Returns a list of buckets for the specified S3 account, including information on storage usage, quota, metrics, and access keys. Uses an asynchronous request via a task queue.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_buckets`
token	✅	string	User authorization token
s3uid	✅	string	Unique S3 user identifier
id	❌	int	Client ID (for administrators)

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=get_buckets" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE"

Example of a successful response

{
"result": "OK",
"action": "get_buckets",
"message": [
{
"name": "my-bucket-01",
"creation_date": "2023-10-15T10:30:00Z",
"usage": 1073741824
},
{
"name": "my-bucket-02",
"creation_date": "2023-11-20T14:45:00Z",
"usage": 536870912
}
],
"usage_storage": 1610612736,
"quota": 5000,
"metering": {
"total_traffic_period_gb": 12.5,
"total_storage_peak_gb": 1.5
},
"access_key": "AKIAIOSFODNN7EXAMPLE",
"secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"endpoint": "https://s3.nl.hostkey.com"
}

Failure response

``` { "code": -1, "message": "S3 account not found for this customer" }

```

s3/get_buckets_rmq¶

Returns a list of S3 user buckets, information on storage usage, quota, traffic metrics, and access keys. Uses a message queue (RMQ) to retrieve current data.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_buckets_rmq`
token	✅	string	User authorization token
s3uid	✅	string	Unique S3 user identifier (S3 UID)
id	❌	int	Client ID (used by administrators to request data for another user)

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=get_buckets_rmq" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE"

Example of a successful response

{
"result": "OK",
"action": "get_buckets_rmq",
"message": [
{
"name": "my-bucket-01",
"usage": 1024000,
"created": "2023-10-15T10:30:00Z"
},
{
"name": "backup-data",
"usage": 5120000,
"created": "2023-11-20T14:45:00Z"
}
],
"usage_storage": 6144000,
"quota": 5000,
"metering": {
"total_traffic_period_gb": 12.5,
"total_storage_peak_gb": 5.96
},
"access_key": "AKIAIOSFODNN7EXAMPLE",
"secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"endpoint": "https://s3.nl.hostkey.com"
}

Failure response

``` { "code": -1, "message": "s3/get_buckets_rmq: S3 account not found for this customer" }

```

s3/get_files¶

Returns a list of files and folders in the specified S3 bucket with pagination and search support.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_files`
token	✅	string	User authorization token
s3uid	✅	string	Unique S3 user identifier
bucket_name	✅	string	Name of the bucket whose contents need to be retrieved
continuation_token	❌	string	Token to continue pagination (if any)
max_keys	❌	int	Maximum number of keys to return (default 50, max 100)
search	❌	string	Search string by file name

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=get_files" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE" \
--data "bucket_name=VALUE"

Example of a successful response

{
"result": "OK",
"action": "get_files",
"files": {
"files": [
{
"key": "documents/report_2023.pdf",
"original_key": "documents/report_2023.pdf",
"size": 2048576,
"last_modified": "2023-10-25T14:30:00Z",
"etag": "\"d41d8cd98f00b204e9800998ecf8427e\""
},
{
"key": "images/logo.png",
"original_key": "images/logo.png",
"size": 15432,
"last_modified": "2023-11-01T09:15:00Z",
"etag": "\"5d41402abc4b2a76b9719d911017c592\""
}
],
"folders": [
"documents/",
"images/"
],
"next_token": "eyJDb250aW51YXRpb25Ub2tlbiI6ImV4YW1wbGUifQ=="
},
"folders": [
"documents/",
"images/"
],
"next_token": "eyJDb250aW51YXRpb25Ub2tlbiI6ImV4YW1wbGUifQ=="
}

Failure response

``` { "code": -1, "message": "s3/get_files: S3 account not found for this customer" }

```

s3/get_users¶

Returns a list of S3 users with information on traffic, storage usage, and service status. Supports filtering by client ID, plan ID, email, billing, s3uid, bucket_name, storage_type. Sorting and pagination are available for administrators.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_users`
token	✅	string	Authorization token
id	❌	int	Client ID (for administrator) or S3 user ID
plan_id	❌	int	S3 billing plan ID
s3uid	❌	string	Unique S3 user identifier
email	❌	string	User email for filtering
billing	❌	string	Billing system for filtering
bucket_name	❌	string	Bucket name to search for user
storage_type	❌	string	Storage type (Standard, Cold, etc.)
location	❌	string	Location (region code, e.g., NL)
period_from	❌	string	Start date of the period for traffic statistics (Y-m-d)
period_to	❌	string	End date of the period for traffic statistics (Y-m-d)
order	❌	string	Field for sorting (total_traffic_period_gb, total_storage_peak_gb)
order_by	❌	string	Sorting direction (ASC, DESC)
limit	❌	int	Number of records to return
offset	❌	int	Offset for pagination

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=get_users" \
--data "token=HOSTKEY_TOKEN"

Example of a successful response

{
"result": "OK",
"action": "get_users",
"s3_users": [
{
"id": 123,
"s3uid": "7VT1xrnQbWSIQhoOrAngpLUL5reuFcXY",
"email": "[email protected]",
"billing": "whmcs",
"plan_id": 5,
"location": "NL",
"storage_type": "Standard",
"quota": 5000,
"traffic": 12.5,
"storage_usage": 45.2,
"service": {
"next_commit_date": "2024-02-01",
"cancellation_date": null,
"termination_date": null,
"termination_unix_date": null,
"cancellation_unix_date": null,
"status": "active"
}
}
]
}

Failure response

``` { "code": -1, "message": "s3/get_users: customer not found" }

```

s3/history¶

Returns the history of changes or events related to the specified S3 billing plan.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `history`
token	✅	string	User authorization token
id	❌	int	S3 billing plan identifier

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=history" \
--data "token=HOSTKEY_TOKEN"

Example of a successful response

{
"result": "OK",
"action": "history",
"data": []
}

Failure response

``` { "code": -1, "message": "s3/history: invalid token, logout" }

```

s3/list_plans¶

Returns a list of available S3 billing plans. Hides inactive plans for clients (if no s3_test tag). For administrators, specifying id returns details of a specific plan.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `list_plans`
token	✅	string	User authorization token
id	❌	int	Plan ID. If specified by an administrator, returns details of a specific plan instead of a list.

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=list_plans" \
--data "token=HOSTKEY_TOKEN"

Example of a successful response

{
"result": "OK",
"action": "list_plans",
"plans": [
{
"id": 1,
"name": "Standard S3",
"active": 1,
"quota": 5000,
"storage_type": "Standard",
"locations": "NL,DE",
"monthly_rub": 4500,
"monthly_eur": 49.99,
"monthly_usd": 54.99,
"traffic_overage_price_rub": 10,
"traffic_overage_price_eur": 0.11,
"traffic_overage_price_usd": 0.12,
"storage_overage_price_rub": 5,
"storage_overage_price_eur": 0.05,
"storage_overage_price_usd": 0.06,
"bandwidth_limit": 1000,
"price": {
"rub": 4500,
"eur": 49.99,
"usd": 54.99
},
"tags": []
}
]
}

Failure response

``` { "code": -1, "message": "s3/list_plans: missing auth token" }

```

s3/show_key¶

Returns the decrypted access key (access_key or secret_key) for the specified S3 account.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `show_key`
token	✅	string	User authorization token
s3uid	✅	string	Unique S3 user identifier
s3_key	✅	string	Key type to retrieve: 'access_key' or 'secret_key'

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=show_key" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE" \
--data "s3_key=VALUE"

Example of a successful response

{
"result": "OK",
"action": "show_key",
"key": "4KCTQIAZ1GLPB8TFIMTO"
}

Failure response

{
"code": -1,
"message": "s3/show_key: customer not found"
}