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 (via order creation)	Creates a new user's S3 account linked to a pricing plan, with automatic creation of a billing order in WHMCS.
`create_bucket`	create S3 bucket	Creates a new S3 bucket for the user, linked to their existing account.
`create_order`	create S3 account order	Creates a new S3 account linked to a pricing plan, including bucket creation and payment order processing in WHMCS.
`delete_account`	delete account	Deletes the user's S3 account, performs an action audit, and logs the operation in history.
`delete_bucket`	delete S3 bucket	Deletes the specified bucket from storage if it belongs to the user.
`delete_file`	delete file	Deletes the specified file from the S3 bucket. Requires authorization and verification of the user's access rights to the account.
`delete_payment_account`	delete payment account (subscription cancellation request)	Requests cancellation of the S3 service and subsequent deletion of the payment account. The method checks for an active service linked to the user and initiates the annulment process.
`get_buckets`	get list of buckets (commented out)	Method intended to retrieve a list of S3 buckets, usage information, and snapshots. In the current code version, this method is commented out.
`get_buckets_rmq`	get bucket information via RMQ	Returns a list of user buckets, their usage, quota, metric data, and S3 credentials.
`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 users list	Returns a list of S3 users with traffic, storage, and service data. Supports filtering by plan, email, billing, s3uid, and location.
`history`	get history	Returns the event history for the specified S3 plan.
`list_plans`	get plans lists	Returns a list of available S3 plans considering user permissions and location. For administrators, it returns the full list; for users, only active plans with prices in their currency.
`show_key`	get S3 access keys	Returns the decrypted secret key or public access key (access_key) for the specified S3 account.

s3/cancel_payment_account_deletion¶

Cancels the service cancellation process for an S3 account, restoring its status.

HTTP-method: POST|GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `cancel_payment_account_deletion`
token	✅	string	Authorization token
s3uid	✅	string	S3 UID of the account

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 account not found for this customer" }

```

s3/create_account¶

Creates a new user's S3 account linked to a pricing plan, with automatic creation of a billing order in WHMCS.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Action command (must be `create_order` to create an account)
token	✅	string	Authorization token
plan_id	✅	int	ID of the selected pricing plan
bucket_name	✅	string	Name of the bucket being created
location	❌	string	Location (region) for data placement

Example Request

curl -s "https://invapi.hostkey.com/s3.php" -X POST \
--data "action=create_order" \
--data "token=YOUR_TOKEN" \
--data "plan_id=123" \
--data "bucket_name=my-new-bucket" \
--data "location=us-east-1"

Example of a successful response

{
"result": "OK",
"action": "create_order",
"s3uid": "string"
}

Failure response

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

```

s3/create_bucket¶

Creates a new S3 bucket for the user, linked to their existing account.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `create_bucket`
token	✅	string	Authorization token
s3uid	✅	string	Unique S3 account UID 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

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

```

s3/create_order¶

Creates a new S3 account linked to a pricing plan, including bucket creation and payment order processing in WHMCS.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `create_order`
token	✅	string	Authorization token
plan_id	✅	int	S3 pricing plan ID
bucket_name	✅	string	Name of the bucket being created
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 "plan_id=VALUE" \
--data "bucket_name=VALUE"

Example of a successful response

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

Failure response

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

```

s3/delete_account¶

Deletes the user's S3 account, performs an action audit, and logs the operation in history.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
token	✅	string	Authorization token
id	❌	int	User ID (for administrators)
s3uid	✅	string	Unique S3 account UID
reason	❌	string	Reason for account deletion

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": "delete_account",
"cancellation_date": "2024-12-31 23:59:59"
}

Failure response

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

```

s3/delete_bucket¶

Deletes the specified bucket from 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	User ID (for administrators)
s3uid	✅	string	S3 account 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": "Object"
}

Failure response

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

```

s3/delete_file¶

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

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Action command (`delete_file`)
token	✅	string	Authorization token
s3uid	✅	string	Unique S3 account UID
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 "action=delete_file" \
--data "token=YOUR_TOKEN" \
--data "s3uid=YOUR_S3UID" \
--data "bucket_name=YOUR_BUCKET_NAME" \
--data "filename=path/to/file.ext"

Example of a successful response

{
"result": "OK",
"action": "delete_file",
"message": "File deleted successfully"
}

Failure response

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

```

s3/delete_payment_account¶

Requests cancellation of the S3 service and subsequent deletion of the payment account. The method checks for an active service linked to the user and initiates the annulment process.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `delete_payment_account`
token	✅	string	Authorization token
id	❌	integer	User ID (used for administrators)
s3uid	✅	string	S3 account UID

Example Request

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

Example of a successful response

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

Failure response

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

```

s3/get_buckets¶

Method intended to retrieve a list of S3 buckets, usage information, and snapshots. In the current code version, this method is commented out.

HTTP-method: POST|GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	API action
token	✅	string	Authorization token
id	❌	integer	User ID (for admin)
s3uid	❌	string	User's S3 UID for account ownership verification

Example Request

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

Example of a successful response

{
"result": "OK",
"action": "get_buckets",
"message": [
{
"Name": "bucket-name",
"Usage": 1024
}
],
"bandwidth": 512,
"snapshot": {
"bandwidth_usage": 1024,
"storage_usage": 5120,
"created_at": "2024-01-15T10:30:00Z"
}
}

Failure response

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

```

s3/get_buckets_rmq¶

Returns a list of user buckets, their usage, quota, metric data, and S3 credentials.

HTTP-method: POST|GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Action: `get_user_info` (used for routing in the context of this method)
token	✅	string	Authorization token
id	❌	int	Client ID (for administrators)
s3uid	✅	string	User's S3 UID

Example Request

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

Example of a successful response

{
"result": "OK",
"action": "get_buckets_rmq",
"message": [
{
"name": "example-bucket",
"usage": 1024
},
{
"name": "test-bucket",
"usage": 512
}
],
"usage_storage": 1536,
"quota": 5000,
"metering": {
"total_traffic_gb": 1.5,
"total_storage_gb": 10.2
},
"access_key": "AKIAIOSFODNN7EXAMPLE",
"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 and search support.

HTTP-method: POST|GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_files`
token	✅	string	Authorization token
s3uid	✅	string	Unique S3 account UID
bucket_name	✅	string	Bucket name
continuation_token	❌	string	Pagination token (next page)
max_keys	❌	int	Maximum number of keys in the response (max. 100)
search	❌	string	Search query 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": {
"items": [
{
"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_continuation_token"
}

Failure response

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

s3/get_users¶

Returns a list of S3 users with information on traffic, storage, and service data. Supports filtering by plan, email, billing, s3uid, and location.

HTTP-method: POST|GET

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 S3 UID
email	❌	string	User's email
billing	❌	string	Billing location
bucket_name	❌	string	Bucket name (for s3uid lookup)
location	❌	string	Location
storage_type	❌	string	Storage type
period_from	❌	string	Start date of the period (Y-m-d)
period_to	❌	string	End date of the period (Y-m-d)
offset	❌	integer	Pagination offset
limit	❌	integer	Number of records per page
order	❌	string	Sorting field (`total_traffic_period_gb` or `total_storage_peak_gb`)
order_by	❌	string	Sort 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": "abc-123-def",
"email": "[email protected]",
"region": "US",
"billing": "USD",
"currency": "USD",
"traffic": 50.5,
"storage_usage": 1024,
"price": {
"base_price": 10.0,
"price": 10.0
},
"service": {
"id": 456,
"entity_id": 123,
"service_ident": "srv_abc123",
"period": "monthly",
"period_start": "2024-01-01T00:00:00Z",
"period_end": "2024-02-01T00:00:00Z",
"next_commit_date": "2024-02-01T00:00:00Z",
"status": "active"
}
}
]
}

Failure response

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

```

s3/history¶

Returns the event history for the specified S3 plan.

HTTP-method: POST|GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `history`
id	✅	int	S3 plan ID
token	✅	string	Authorization token

Example Request

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

Example of a successful response

{
"result": "OK",
"action": "history",
"data": [
{
"id": 123,
"event": "plan_updated",
"description": "Plan configuration changed",
"created_at": "2024-05-20T12:00:00Z"
}
]
}

Failure response

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

```

s3/list_plans¶

Returns a list of available S3 plans considering user permissions and location. For administrators, it returns the full list; for users, only active plans with prices in their currency.

HTTP-method: POST|GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `list_plans`
token	✅	string	Authorization token
id	❌	int	Specific plan ID (for administrators)

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 Plan",
"active": 1,
"storage_type": "standard",
"location": "NL",
"price": {
"base_price": 10.0,
"price": {
"USD": 10.5,
"EUR": 9.8,
"RUB": 950
}
},
"traffic_overage_price": {
"usd": 0.01,
"eur": 0.01,
"rub": 1
},
"storage_overage_price": {
"usd": 0.05,
"eur": 0.05,
"rub": 5
}
}
]
}

Failure response

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

```

s3/show_key¶

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

HTTP-method: POST|GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Action command: `show_key`
token	✅	string	Authorization token
s3uid	✅	string	Unique S3 account UID
s3_key	✅	string	Type of 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=YOUR_TOKEN" \
--data "s3uid=YOUR_S3UID" \
--data "s3_key=secret_key"

Example of a successful response

{
"result": "OK",
"action": "show_key",
"key": "wJalrXUtnFEMI/KxvUXCDAWSGlS7v69pYV8L3m5fG2A="
}

Failure response

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