auth.php¶

Authentication and authorization module: session management, login via WHMCS, LDAP, API keys, and SSO (Google, GitHub, VK), 2FA verification, SMS and email verification, as well as client tag management.

API Methods¶

Method	Action	Description
`2fa_check`	2FA code verification	Verifies the two-factor authentication code passed in the user_token parameter.
`2fa_resend`	resend 2FA code	Requests a resend of the 2FA code to the bound method.
`billing_list`	get billing list	Returns a list of available billing systems (WHMCS) for the current domain or user.
`email_check`	email verification	Initializes or verifies the user's email address verification.
`flip_tag`	toggle tag	Sets or removes a tag for a client (e.g., auto_credit).
`get_log`	get authorization log	Returns the authorization event log for a specified period or by token.
`get_log_details`	authorization log details	Returns detailed information about a specific log event by token.
`github_init`	initialize GitHub SSO	Returns data to initialize the OAuth flow with GitHub.
`github_signin`	login via GitHub	Processes the OAuth code from GitHub for login or account linking.
`google_signin`	login via Google	Processes the JWT token from Google for login or account linking.
`info`	token information	Returns information about the current session, access rights, servers, and billing.
`ipalogin`	login via LDAP (IPA)	Authorizes an employee via LDAP (IPA) with the ability to bind to a server.
`login`	login by API key	Authorizes a client or server by API key.
`logout`	logout	Clears the current session token.
`session_reset`	reset sessions	Resets all active user sessions by email and reset token.
`set_tag`	set tag	Sets or removes a tag for a client with the ability to specify a value.
`tg_verify`	Telegram verification	Binds a Telegram username to the user account.
`vk_init`	initialize VK SSO	Returns data to initialize the OAuth flow with VK ID.
`vk_signin`	login via VK	Processes the OAuth code from VK for login or account linking.
`whmcslogin`	login via WHMCS	Main login method via WHMCS credentials (email/password) or SSO.

auth/2fa_check¶

Verifies the two-factor authentication code passed in the user_token parameter.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `2fa_check`
token	✅	string	User session token
user_token	✅	string	Two-factor authentication code

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=2fa_check" \
--data "token=HOSTKEY_TOKEN" \
--data "user_token=VALUE"

Example of a successful response

{
"result": "2FA OK"
}

Failure response

{
"code": -1,
"message": "Invalid verification token"
}

auth/2fa_resend¶

Requests a resend of the 2FA code to the bound method.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `2fa_resend`
token	✅	string	User session token
from	❌	string	Request source (user_profile, resend_dialog)

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=2fa_resend" \
--data "token=HOSTKEY_TOKEN"

Example of a successful response

{
"result": "OK",
"message": "2FA token sent"
}

Failure response

{
"code": -1,
"message": "Invalid customer record"
}

auth/billing_list¶

Returns a list of available billing systems (WHMCS) for the current domain or user.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `billing_list`
token	❌	string	Session token for authorization. If not provided, returns the list for all billings.

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=billing_list"

Example of a successful response

{
"result": "OK",
"billings": [
{
"billing": "whmcs",
"company": "HostKey",
"location": "NL"
}
]
}

Failure response

{
"code": -2,
"message": "auth: invalid token"
}

auth/email_check¶

Initializes or verifies the user's email address verification.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `email_check`
user_email	✅	string	Email address for verification
location	✅	string	Billing location (e.g., US, EU)
user_token	❌	string	Confirmation code sent to email (for the verification stage)

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=email_check" \
--data "[email protected]" \
--data "location=US"

Example of a successful response

{
"result": "OK",
"state": "sent",
"message": "Verification email sent to [email protected], please confirm in 15 minutes"
}

Failure response

{
"code": -1,
"message": "Email verification timeout: please start again"
}

auth/flip_tag¶

Sets or removes a tag for a client (e.g., auto_credit).

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `flip_tag`
token	✅	string	Session token
tag	✅	string	Tag name to toggle (only 'auto_credit' is allowed for the user role)

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=flip_tag" \
--data "token=HOSTKEY_TOKEN" \
--data "tag=VALUE"

Example of a successful response

{
"result": "OK",
"message": "auth/flip_tag: tag auto_credit created",
"action": "created"
}

Failure response

{
"code": -1,
"message": "auth/flip_tag: invalid tag"
}

auth/get_log¶

Returns the authorization event log for a specified period or by token.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_log`
token	✅	string	Session token
user_token	❌	string	User token for log search
period_start	❌	string	Period start (YYYY-MM-DD)
period_stop	❌	string	Period end (YYYY-MM-DD)
user_email	❌	string	User email for log filtering

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=get_log" \
--data "token=HOSTKEY_TOKEN"

Example of a successful response

{
"result": "OK",
"data": [
{
"id": 123,
"action": "login",
"ip": "1.2.3.4",
"time": "2024-01-15 10:00:00"
}
]
}

Failure response

{
"code": 404,
"message": "Log is empty"
}

auth/get_log_details¶

Returns detailed information about a specific log event by token.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_log_details`
token	✅	string	Session token for authorization
user_token	✅	string	Log event token to retrieve details

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=get_log_details" \
--data "token=HOSTKEY_TOKEN" \
--data "user_token=VALUE"

Example of a successful response

{
"result": "OK",
"log": {
"id": 123,
"message": "Successful login",
"ip": "1.2.3.4",
"hash": "abc123...",
"token": "xyz789...",
"level": 0,
"created_at": "2023-10-27 10:00:00"
}
}

Failure response

{
"code": -1,
"message": "Invalid period or log is empty"
}

auth/github_init¶

Returns data to initialize the OAuth flow with GitHub.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `github_init`
-	-	-	No other parameters

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=github_init"

Example of a successful response

{
"result": "OK",
"data": {
"client_id": "gh_client_123",
"redirect_uri": "https://example.com/callback"
},
"error_code": null
}

Failure response

{
"code": -1,
"message": "Configuration error"
}

auth/github_signin¶

Processes the OAuth code from GitHub for login or account linking.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `github_signin`
code	✅	string	OAuth code from GitHub
state	✅	string	State parameter (used as a session token for linking)

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=github_signin" \
--data "code=VALUE" \
--data "state=VALUE" \
--data "token=HOSTKEY_TOKEN"

Example of a successful response

{
"result": "OK",
"sso": "github",
"sso_hash": "abc123..."
}

Failure response

{
"code": -1,
"message": "Error occurred when querying Github"
}

auth/google_signin¶

Processes the JWT token from Google for login or account linking.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `google_signin`
credential	✅	string	JWT token from Google
token	❌	string	Current session token for linking

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=google_signin" \
--data "credential=VALUE"

Example of a successful response

{
"result": "OK",
"sso": "google",
"sso_hash": "def456...",
"error_code": null
}

Failure response

{
"code": -1,
"message": "credential is missing"
}

auth/info¶

Returns information about the current session, access rights, servers, and billing.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `info`
token	✅	string	Session token

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=info" \
--data "token=HOSTKEY_TOKEN"

Example of a successful response

{
"result": {
"token": "abc123",
"role": "Customer",
"role_type": "Customer",
"servers": [
101,
102
],
"whmcs_id": 555,
"permissions": [
"eq_list",
"billing_list"
],
"token_expire": 1705320000,
"email": "[email protected]",
"subaccount": null,
"manage_orders": 0,
"ipsubnet_announce": 0,
"prebill": 0,
"show_products": 0,
"manage_products": 0,
"customer_id": 456,
"billing_servers": null,
"edit_master_profile": 0,
"original_tags": null,
"whmcs_location": "whmcs",
"show_invoices": 0,
"billing_options": {
"url": "https://billing.example.com",
"location": "US",
"company": "Example Inc",
"active": 1,
"allowed_payments": [
"cc",
"pp"
],
"native_endpoint": "https://billing.example.com",
"sumsub_kyc": 1,
"paypal_id": "12345"
},
"verified": 1,
"sumsub_id": "sumsub_123",
"sumsub_comment": "",
"corporate": 0,
"default_lang": "en",
"private_ranges": [],
"private_vlans": [],
"deploy_keys": {},
"client_ip": "192.168.1.1",
"timing": []
}
}

Failure response

{
"code": -2,
"message": "auth: invalid token #13"
}

auth/login¶

Authorizes a client or server by API key.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `login`
key	✅	string	API key
ttl	❌	int	Token lifetime in seconds
base	❌	string	Base URL for invapi (optional)

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=login" \
--data "key=VALUE"

Example of a successful response

{
"result": {
"token": "api_token_123",
"role": "Customer",
"role_type": "Customer",
"whmcs_id": "12345",
"whmcs_location": "whmcs",
"servers": [
101,
102
],
"invapi": "invapi.hostkey.com",
"customer_id": "5678",
"permissions": [
"server/list",
"server/info"
],
"token_expire": 1705327200,
"new": 1,
"prebill": 0
}
}

Failure response

{
"code": -1,
"message": "auth/login: no key specified"
}

auth/logout¶

Clears the current session token.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `logout`
token	✅	string	Session token to remove

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=logout" \
--data "token=HOSTKEY_TOKEN"

Example of a successful response

{
"result": "OK",
"message": "access token cleared"
}

Failure response

{
"code": -2,
"message": "auth: no token specified"
}

auth/session_reset¶

Resets all active user sessions by email and reset token.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `session_reset`
user_email	✅	string	User email whose sessions need to be reset
reset_token	✅	string	Session reset token
confirm	❌	int	Action confirmation flag (1)

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=session_reset" \
--data "[email protected]" \
--data "reset_token=a1b2c3d4e5f6"

Example of a successful response

{
"result": "OK",
"message": "Sessions reset"
}

Failure response

{
"code": -1,
"message": "Invalid reset token"
}

auth/set_tag¶

Sets or removes a tag for a client with the ability to specify a value.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `set_tag`
token	✅	string	Session token
tag	✅	string	Tag name
set	✅	string	Tag value (required parameter according to code)

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=set_tag" \
--data "token=HOSTKEY_TOKEN" \
--data "tag=VALUE" \
--data "set=VALUE"

Example of a successful response

{
"result": "OK",
"message": "auth/set_tag: tag auto_credit created",
"action": "set",
"error_code": null
}

Failure response

{
"code": -1,
"message": "auth/set_tag: tag is missing"
}

auth/tg_verify¶

Binds a Telegram username to the user account.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `tg_verify`
token	✅	string	Session token
tg_username	✅	string	Telegram username (without @)

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=tg_verify" \
--data "token=HOSTKEY_TOKEN" \
--data "tg_username=VALUE"

Example of a successful response

{
"result": "OK",
"bot_url": "https://t.me/hostkey_bot"
}

Failure response

{
"code": -1,
"message": "Illegal TG username"
}

auth/vk_init¶

Returns data to initialize the OAuth flow with VK ID.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `vk_init`
token	❌	string	Current session token (optional, used to bind SSO to an existing user)

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=vk_init"

Example of a successful response

{
"result": "OK",
"data": {
"client_id": "vk_client_id_from_config",
"redirect_uri": "https://example.com/callback",
"code_challenge": "base64url_encoded_sha256_challenge",
"device_id": "random_device_id_24chars",
"state": "random_state_30chars_id6chars"
}
}

Failure response

{
"code": -1,
"message": "Configuration error or internal server error"
}

auth/vk_signin¶

Processes the OAuth code from VK for login or account linking.

HTTP Method: GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `vk_signin`
code	✅	string	OAuth code from VK
state	✅	string	State parameter for CSRF verification
device_id	✅	string	Device ID for the OAuth request
token	❌	string	Authentication API token (optional, for linking to an existing account)

Example Request

curl -s "https://api.hostkey.com/auth.php" -X GET \
--data "action=vk_signin" \
--data "code=VALUE" \
--data "state=VALUE" \
--data "device_id=VALUE"

Example of a successful response

{
"result": "OK",
"sso": "vk",
"sso_hash": "a1b2c3d4e5f6..."
}

Failure response

{
"code": -1,
"message": "no state"
}

auth/whmcslogin¶

Main login method via WHMCS credentials (email/password) or SSO.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `whmcslogin`
user	❌	string	User email (if not SSO)
password	❌	string	User password (if not SSO)
sso	❌	string	SSO type (google, github, vk)
sso_hash	❌	string	SSO session hash
location	❌	string	Billing location (e.g., NL, US). If not specified, Auto is used.
ttl	❌	integer	Token lifetime in seconds (default 86400)
fix_ip	❌	integer	Bind token to IP (1 or 0)
full_customer_data	❌	string	Include full customer data in response (1 or 0)
VisitorID	❌	string	Visitor ID for the affiliate system

Example Request

curl -s "https://api.hostkey.com/auth.php" -X POST \
--data "action=whmcslogin" \
--data "[email protected]" \
--data "password=secret123"

Example of a successful response

{
"result": {
"token": "whmcs_token_123",
"role": "Customer",
"role_type": "Customer",
"whmcs_id": 555,
"whmcs_location": "NL",
"whmcs_token": "",
"permissions": [
"eq_list",
"invoice_list"
],
"corporate": 0,
"verified": "",
"token_expire": 1705330000,
"new": 1,
"country": "Netherlands",
"country_code": "NL",
"currency_code": "EUR",
"vat": "",
"VisitorID": "vis_123",
"prebill": 0,
"billing_options": {
"location": "NL",
"company": "HostKey NL",
"active": 1,
"allowed_payments": [
"cc",
"pp"
],
"native_endpoint": "https://nl.hostkey.com",
"sumsub_kyc": 1
},
"2fa": "sms"
}
}

Failure response

{
"code": -2,
"message": "auth: empty username"
}