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, registers the user, creates a bucket, and processes payment.
`delete_account`	delete S3 account	Completely deletes the user's S3 account, including action audit and history logging. Requires specifying the client ID (for admins) or uses the current user, 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 S3 account 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 account buckets, information on storage usage, quota, traffic metrics, and access keys. Uses a message queue (RMQ) to retrieve 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 history	Returns the history of changes or actions for the specified S3 plan or entity by ID.
`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 requested deletion of 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
id	❌	int	Client ID (for administrators)
s3uid	✅	string	Unique S3 user identifier

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": null
}

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
location	❌	string	Location code (default NL)

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_order",
"s3uid": "7VT1xrnQbWSIQhoOrAngpLUL5reuFcXY"
}

Failure response

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

```

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 (S3 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, registers the user, creates a bucket, and processes payment.

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
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, including action audit and history logging. Requires specifying the client ID (for admins) or uses the current user, 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	User authorization token
id	❌	int	Client ID (used by administrators to delete another user's account)
s3uid	✅	string	Unique S3 user identifier (s3uid)
reason	❌	string	Reason for account deletion (for audit)

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	Authorization token
s3uid	✅	string	Unique S3 user identifier
bucket_name	✅	string	Name of the bucket to delete
id	❌	integer	Client ID (for administrators)

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 S3 account 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": "File deleted successfully"
}

Failure response

``` { "code": -1, "message": "s3/delete_file: Delete S3 file error: Access Denied." }

```

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 (used by administrators to manage other users' accounts)

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 account buckets, information on storage usage, quota, traffic metrics, and access keys. Uses a message queue (RMQ) to retrieve 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
id	❌	int	Client ID (used by administrators to access other users' accounts)

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:00:00Z"
},
{
"name": "backup-data",
"usage": 5120000,
"created": "2023-11-20T14:30: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 objects 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": "eyJDb250aW51YXRpb25Ub2tlbiI6ImV4YW1wbGUiLCJNYXhLZXlzIjo1MH0="
},
"folders": [
"documents/",
"images/"
],
"next_token": "eyJDb250aW51YXRpb25Ub2tlbiI6ImV4YW1wbGUiLCJNYXhLZXlzIjo1MH0="
}

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 user ID
plan_id	❌	int	S3 billing plan ID
s3uid	❌	string	Unique S3 user identifier
email	❌	string	User email for filtering
billing	❌	string	Billing group 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	Sort 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-15",
"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 actions for the specified S3 plan or entity by ID.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `history`
token	✅	string	User authorization token
id	❌	int	Plan or entity identifier for which to retrieve history

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: missing auth token" }

```

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": 1500,
"monthly_eur": 15.0,
"monthly_usd": 16.5,
"bandwidth_limit": 1000,
"traffic_overage_price_rub": 50,
"traffic_overage_price_eur": 0.5,
"traffic_overage_price_usd": 0.55,
"storage_overage_price_rub": 10,
"storage_overage_price_eur": 0.1,
"storage_overage_price_usd": 0.11,
"price": {
"NL": {
"EUR": 15.0,
"USD": 16.5
}
}
}
]
}

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"
}