s3.php¶

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

API Methods¶

Method	Action	Description
`create_account`	create S3 account	Creates a new S3 account (bucket) for the client, links it to a pricing plan, and creates a corresponding order in billing.
`create_bucket`	create bucket	Creates a new S3 bucket for an existing user (S3 account).
`create_order`	create S3 service order	Creates a new S3 account and bucket and links them to a pricing plan via billing. If the plan is free, it checks the limit of free accounts.
`delete_account`	delete account	Deletes the user's S3 account and performs an action audit. If the request is from an administrator, an entry is created in the audit log.
`delete_bucket`	delete S3 bucket	Deletes the specified bucket from S3 storage if it belongs to the user.
`delete_file`	delete file	Deletes the specified file from the S3 bucket. Requires authorization and verification of account access rights.
`delete_payment_account`	delete payment account (subscription cancellation request)	Requests cancellation of the S3 service, initiating the account deletion process. Sets the suspension reason and calculates the service termination date.
`get_buckets`	get buckets list	Returns a list of S3 buckets, traffic information, and snapshots for the specified account.
`get_buckets_rmq`	get bucket info via RMQ	Returns a list of buckets, storage usage information, user quota, metrics data, and billing parameters for a specific S3 account.
`get_files`	get files from S3 bucket	Returns a list of files and folders in the specified S3 bucket with pagination support via continuation token.
`get_users`	get S3 users list	Returns a list of S3 users with detailed information about plans, traffic, and service status. Supports filtering by plan, email, billing, and S3UID.
`history`	get history	Returns the operation history (logs) for the specified S3 plan.
`list_plans`	get plans lists	Returns a list of available S3 plans taking into account the VAT rate and user currency. For administrators, it is possible to request a specific plan by ID.
`show_key`	get S3 access keys	Returns the decrypted secret key or public access key (access_key/secret_key) for the specified S3 account.

s3/cancel_payment_account_deletion¶

Cancels the S3 account deletion process initiated due to debt. Resets the suspension status and updates the next payment date.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
token	✅	string	Authorization token
id	❌	int	Client ID (used for admins)
s3uid	✅	string	Unique S3 account identifier

Example Request

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

Example of a successful response

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

Failure response

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

```

s3/create_account¶

Creates a new S3 account (bucket) for the client, links it to a pricing plan, and creates a corresponding order in billing.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `create_account`
token	✅	string	Authorization token
bucket_name	✅	string	Name of the bucket being created
plan_id	✅	int	Pricing plan ID
location	❌	string	Data storage location (region). Default is NL.

Example Request

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

Example of a successful response

{
"result": "OK",
"action": "create_account",
"s3uid": "5f8e9d2a1b0c4e3f7a6b5d4c3e2f1a0b"
}

Failure response

``` { "code": -1, "message": "S3 account was being created, however a bucket creation error occurred - Invalid bucket name." }

```

s3/create_bucket¶

Creates a new S3 bucket for an existing user (S3 account).

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `create_bucket`
token	✅	string	Authorization token
s3uid	✅	string	Unique S3 account identifier of the user
bucket_name	✅	string	Name of the bucket being 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"
}
}

Failure response

``` { "-1": { "code": -1, "message": "S3 account not found for this customer" }, "-2": { "code": -1, "message": "Create bucket error: Invalid bucket name." } }

```

s3/create_order¶

Creates a new S3 account and bucket and links them to a pricing plan via billing. If the plan is free, it checks the limit of free accounts.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `create_order`
token	✅	string	Authorization token
bucket_name	✅	string	Name of the bucket being created
plan_id	✅	int	Selected pricing plan ID
location	❌	string	Data storage location (region). Default is NL.

Example Request

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

Example of a successful response

{
"result": "OK",
"action": "create_order",
"s3uid": "5f8e2a1b9c0d4e3f7a6b5c4d3e2f1a0b"
}

Failure response

``` { "code": -1, "message": "S3 account was being created, however a bucket creation error occurred - [error]" }

```

s3/delete_account¶

Deletes the user's S3 account and performs an action audit. If the request is from an administrator, an entry is created in the audit log.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `delete_account`
token	✅	string	Authorization token
id	❌	int	Client ID (for administrators)
s3uid	✅	string	Unique S3 account identifier
reason	❌	string	Reason for account deletion

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=delete_account" \
--data "token=YOUR_TOKEN" \
--data "s3uid=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 bucket from S3 storage if it belongs to the user.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `delete_bucket`
token	✅	string	Authorization token
id	❌	integer	Client ID (for administrators)
s3uid	✅	string	User's S3 UID
bucket_name	✅	string	Name of the bucket to be deleted

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": {
"status": "success",
"details": "Bucket deleted successfully"
}
}

Failure response

``` { "code": -1, "message": "Delete S3 bucket error: Bucket not found or access denied" }

```

s3/delete_file¶

Deletes the specified file from the S3 bucket. Requires authorization and verification of account access rights.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
token	✅	string	Authorization token
s3uid	✅	string	Unique S3 account identifier
bucket_name	✅	string	Bucket name
filename	✅	string	Path or name of the file to be deleted

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--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 successfully deleted"
}

Failure response

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

```

s3/delete_payment_account¶

Requests cancellation of the S3 service, initiating the account deletion process. Sets the suspension reason and calculates the service termination date.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `delete_payment_account`
token	✅	string	Authorization token
id	❌	int	User ID (for administrator)
s3uid	✅	string	S3 account UID
reason	❌	string	Reason for deletion/suspension

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",
"cancellation_date_origin": "31.12.2024",
"reason_suspend": "User requested deletion"
}

Failure response

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

```

s3/get_buckets¶

Returns a list of S3 buckets, traffic information, and snapshots for the specified account.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_buckets`
token	✅	string	Authorization token
id	❌	integer	Client ID (for admin)
s3uid	✅	string	User's S3 UID

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-name",
"usage": 1024,
"created_at": "2024-01-15T10:30:00Z"
}
],
"bandwidth": 512,
"quota": 5000,
"snapshot": {
"bandwidth_usage": 100,
"storage_usage": 500,
"created_at": "2024-05-20T12:00:00Z"
},
"metering": {},
"billing": {
"service_id": 123,
"currency": "EUR",
"period": {
"start": "2024-05-01T00:00:00Z",
"end": "2024-06-01T00:00:00Z"
},
"limits": {
"traffic_gb": 100,
"storage_gb": 500
},
"current_period": {
"traffic_used_gb": 10.5,
"storage_used_gb": 45.2,
"billed_traffic_gb": 0,
"billed_storage_gb": 0,
"billed_traffic_amount": 0,
"billed_storage_amount": 0
},
"overage": null,
"records": [],
"error": "billing_unavailable"
},
"access_key": "AKIAEXAMPLE123456789",
"secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"endpoint": "s3.eu-central-1.amazonaws.com"
}

Failure response

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

```

s3/get_buckets_rmq¶

Returns a list of buckets, storage usage information, user quota, metrics data, and billing parameters for a specific S3 account.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_buckets_rmq`
token	✅	string	Authorization token
id	❌	int	Client ID (used for admins)
s3uid	✅	string	Unique S3 account identifier

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": "bucket-1",
"usage": 1024
},
{
"name": "bucket-2",
"usage": 512
}
],
"usage_storage": 1536,
"quota": 5000,
"metering": {
"total_traffic_gb": 15.5,
"total_storage_peak_gb": 2.4
},
"billing": {
"service_id": 123,
"currency": "EUR",
"period": {
"start": "2024-01-01 00:00:00",
"end": "2024-02-01 00:00:00"
},
"limits": {
"traffic_gb": 100.0,
"storage_gb": 500
},
"current_period": {
"traffic_used_gb": 15.5,
"storage_used_gb": 2.4,
"billed_traffic_gb": 0,
"billed_storage_gb": 0,
"billed_traffic_amount": 0,
"billed_storage_amount": 0
},
"overage": null,
"records": [],
"error": "billing_unavailable"
},
"access_key": "AKIAEXAMPLE123456789",
"secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"endpoint": "s3.nl.example.com"
}

Failure response

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

```

s3/get_files¶

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

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_files`
token	✅	string	Authorization token
s3uid	✅	string	Unique S3 account identifier
bucket_name	✅	string	Bucket name
continuation_token	❌	string	Token for pagination (next page)
max_keys	❌	int	Maximum number of keys in the response (max. 100)
search	❌	string	Search by filename

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": [
{
"key": "folder/file.txt",
"original_key": "folder/file.txt",
"size": 1024,
"last_modified": "2024-05-20T12:00:00Z"
}
],
"folders": [
{
"key": "folder/",
"original_key": "folder/"
}
],
"next_token": "example_token_string"
}

Failure response

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

```

s3/get_users¶

Returns a list of S3 users with detailed information about plans, traffic, and service status. Supports filtering by plan, email, billing, and S3UID.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_users`
token	✅	string	Authorization token
id	❌	integer	Client ID (for admin)
plan_id	❌	integer	Pricing plan ID
s3uid	❌	string	User's S3UID
email	❌	string	User email for search
billing	❌	string	Billing location (e.g., whmcs_itb)
storage_type	❌	string	Storage type
location	❌	string	Location (e.g., NL)
period_from	❌	string	Period start date (YYYY-MM-DD)
period_to	❌	string	Period end date (YYYY-MM-DD)
offset	❌	integer	Offset for pagination
limit	❌	integer	Number of records per page
order	❌	string	Field for sorting (total_traffic_period_gb or total_storage_peak_gb)
order_by	❌	string	Sorting direction (ASC/DESC)

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": "b8815338-test",
"email": "[email protected]",
"billing": "whmcs_itb",
"region": "NL",
"storage_type": "Standard",
"traffic": 10.5,
"storage_usage": 500,
"price": {
"EUR": 49.99,
"USD": 4500
},
"service": {
"id": 55,
"entity_id": 123,
"rate": 49.99,
"status": "active",
"period_start": "2024-01-01T00:00:00Z",
"period_end": "2024-02-01T00:00:00Z",
"next_commit_date": "2024-02-01T00:00:00Z"
}
}
]
}

Failure response

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

```

s3/history¶

Returns the operation history (logs) for the specified S3 plan.

HTTP-method: POST|GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `history`
token	✅	string	Authorization token
id	❌	integer	S3 plan ID to retrieve history for

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": [
{
"id": 12345,
"event": "S3 service [ID=10] created",
"customer_id": 55,
"type": "billing",
"created_at": "2024-05-20T12:00:00Z"
}
]
}

Failure response

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

```

s3/list_plans¶

Returns a list of available S3 plans taking into account the VAT rate and user currency. For administrators, it is possible to request a specific plan by ID.

HTTP-method: POST|GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `list_plans`
token	✅	string	Authorization token
id	❌	int	Specific plan ID (used by administrator to get a single plan)

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 Plan",
"active": 1,
"storage_type": "standard",
"location": "NL",
"price": {
"base_price": 10.0,
"EUR": 10.0
},
"traffic_overage_price": {
"RUB": 500,
"EUR": 5
},
"storage_overage_price": {
"RUB": 2000,
"EUR": 20
}
}
],
"vat": 1.2
}

Failure response

``` { "code": -1, "message": "action required" }

```

s3/show_key¶

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

HTTP-method: POST|GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `show_key`
token	✅	string	Authorization token
s3uid	✅	string	Unique S3 account identifier
s3_key	✅	string	Type of the requested key (secret_key or access_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": "AKIAIOSFODNN7EXAMPLE"
}

Failure response

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