auth.php¶

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

API Methods¶

Method	Action	Description
`2fa_check`	2FA code check	Validates the two-factor authentication code passed in the `user_token` parameter. Requires a valid session token.
`2fa_resend`	resend 2FA code	Resends the two-factor authentication code to the linked method (email or SMS). Requires a valid session token.
`billing_list`	get billing list	Returns a list of available billing systems (WHMCS) for the current deployment domain. If a valid token is passed, the list is filtered by the user's or administrator's location.
`email_check`	email check	Client email validation, sending a confirmation code, or checking the entered code.
`flip_tag`	toggle tag	Enables or disables the specified tag for the current user. If the tag exists, it is removed. If it does not exist, it is created.
`get_log`	get auth log	Returns the authorization event log for the specified period or by token.
`get_log_details`	get auth log details	Returns detailed information about an authorization log entry by the specified user token. Requires a valid session token and `auth/get_log` access rights.
`github_init`	initialize GitHub login	Returns data for initializing OAuth authorization via GitHub (`client_id` and `redirect_uri`).
`github_signin`	authorize via GitHub	Handles the callback from GitHub OAuth. Exchanges the code for an access token, retrieves user data, and links the GitHub account to the current session or creates a new SSO link.
`google_signin`	authorize via Google SSO	Handles login via Google. Checks the JWT token, links the Google account to an existing user (if `token` is passed), or returns data for subsequent login.
`info`	get token info	Returns detailed information about the current token: role, access rights, server list, verification status, billing settings, and private IP ranges.
`ipalogin`	login via LDAP (IPA)	Employee authorization via LDAP (IPA) with the ability to link to a server.
`login`	get token by API key	Returns an access token for the API based on the provided client API key. Checks key validity, access rights, and IP address binding.
`logout`	logout	Clears the access token and terminates the current user session.
`session_reset`	reset session	Forcefully terminates all active user sessions by email and reset token, clears associated tags, and redirects to the login page.
`set_tag`	set or remove user tag	Sets or removes the specified tag for the current authenticated user. Available only for administrators or for clients to set the 'auto_credit' tag.
`tg_verify`	verify Telegram	Links the specified Telegram username to the current user's account and returns a link to the notification bot.
`vk_init`	initialize VK login	Generates parameters to start the OAuth authorization process via VKontakte (`client_id`, `redirect_uri`, `code_challenge`, `device_id`, `state`) and saves the verification code to the database.
`vk_signin`	complete VK ID login	Handles the callback from VK ID after authorization. Exchanges the code for a token, checks `state` and `code_verifier`, links the VK account to the platform user, or redirects to the login page with an SSO hash.
`whmcslogin`	authenticate user via WHMCS	Logs into the system using WHMCS credentials (email/password) or SSO. Returns an access token, role information, access rights, and client details. Supports login via SSO (Google, VK) and standard authentication.

auth/2fa_check¶

Validates the two-factor authentication code passed in the user_token parameter. Requires a valid session token.

HTTP Method: POST

Parameters:

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

Example Request

curl -s "https://invapi.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": -2,
"message": "auth: invalid token"
}

auth/2fa_resend¶

Resends the two-factor authentication code to the linked method (email or SMS). Requires a valid session token.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `2fa_resend`
token	✅	string	User authentication token
from	❌	string	Request source: 'user_profile' or 'resend_dialog'. Affects 2FA session clearing logic.

Example Request

curl -s "https://invapi.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": -2,
"message": "Invalid customer record",
"details": "Error retrieving client data or invalid token"
}

auth/billing_list¶

Returns a list of available billing systems (WHMCS) for the current deployment domain. If a valid token is passed, the list is filtered by the user's or administrator's location.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `billing_list`
token	❌	string	Authentication token. If passed, the list is filtered by the user's (customer) location or returns all billings (admin). If not passed, a general list for the site is returned.

Example Request

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

Example of a successful response

{
"result": "OK",
"billings": [
{
"HTTP_HOST": "billing1.hostkey.com",
"PAYPAL_ID": "paypal_merchant_id_1",
"active": 1,
"admin_url": "https://billing1.hostkey.com/admin",
"allowed_endpoints": [
"api",
"client"
],
"company": "HostKey LLC",
"location": "US",
"url": "https://billing1.hostkey.com"
}
]
}

Failure response

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

```

auth/email_check¶

Client email validation, sending a confirmation code, or checking the entered code.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `email_check`
user_email	✅	string	Email address for checking or verification
location	✅	string	Billing location
user_token	❌	string	Confirmation code sent to email

Example Request

curl -s "https://invapi.hostkey.com/auth.php" -X POST \
--data "action=email_check" \
--data "user_email=VALUE" \
--data "location=VALUE"

Example of a successful response

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

Failure response

{
"code": -2,
"message": "auth/email_check: invalid email [email protected]",
"details": {
"result": "Fail",
"state": "fail",
"error": "auth/email_check: invalid email [email protected]"
}
}

auth/flip_tag¶

Enables or disables the specified tag for the current user. If the tag exists, it is removed. If it does not exist, it is created.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `flip_tag`
token	✅	string	User authentication token
tag	✅	string	Tag name to toggle (e.g., auto_credit). Length no more than 32 characters.

Example Request

curl -s "https://invapi.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": "error",
"message": "auth/flip_tag: tag is missing"
}

auth/get_log¶

Returns the authorization event log for the 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 to search for the log
period_start	❌	string	Start of period (YYYY-MM-DD)
period_stop	❌	string	End of period (YYYY-MM-DD)
user_email	❌	string	User email to filter the log

Example Request

curl -s "https://invapi.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 an authorization log entry by the specified user token. Requires a valid session token and auth/get_log access rights.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_log_details`
token	✅	string	Session authorization token to check access rights
user_token	✅	string	User token for which log details are requested

Example Request

curl -s "https://invapi.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": 12345,
"hash": "a1b2c3d4e5f6...",
"token": "xyz789...",
"log": "successful login via whmcs from remote IP:192.168.1.1",
"level": 0,
"created_at": "2023-10-27T10:30:00Z",
"ip": "192.168.1.1",
"user_agent": "Mozilla/5.0 ..."
}
}

Failure response

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

```

auth/github_init¶

Returns data for initializing OAuth authorization via GitHub (client_id and redirect_uri).

HTTP Method: POST

Parameters:

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

Example Request

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

Example of a successful response

{
"result": "OK",
"data": {
"client_id": "string",
"redirect_uri": "string"
},
"error_code": null
}

Failure response

{
"code": null,
"message": "No explicit error responses defined in code"
}

auth/github_signin¶

Handles the callback from GitHub OAuth. Exchanges the code for an access token, retrieves user data, and links the GitHub account to the current session or creates a new SSO link.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `github_signin`
code	✅	string	Authorization code received from GitHub OAuth
state	❌	string	Current user session token (for linking the account)

Example Request

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

Example of a successful response

{
"result": "Redirect",
"message": "Redirect to host with sso=github&sso_hash=..."
}

Failure response

{
"code": -1,
"message": "Invalid host header",
"details": "Host header validation error"
}

auth/google_signin¶

Handles login via Google. Checks the JWT token, links the Google account to an existing user (if token is passed), or returns data for subsequent login.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `google_signin`
credential	✅	string	JWT token from Google Identity Services
token	❌	string	Existing user session token (to link the Google account to the current session)

Example Request

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

Example of a successful response

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

Failure response

{
"code": -1,
"message": "auth/google_signin: credential is missing",
"error_code": "MISSING_CREDENTIAL"
}

auth/info¶

Returns detailed information about the current token: role, access rights, server list, verification status, billing settings, and private IP ranges.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `info`
token	✅	string	Authentication token received upon login.

Example Request

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

Example of a successful response

{
"result": {
"servers": [
12345,
67890
],
"show_products": 1,
"manage_products": 1,
"show_invoices": 1,
"manage_orders": 1,
"ipsubnet_announce": 1,
"edit_master_profile": 1,
"email": "[email protected]",
"whmcs_id": 98765,
"whmcs_location": "NL",
"token_expire": 1715000000,
"subaccount": null,
"prebill": 0,
"customer_id": 54321,
"2fa": "email",
"role_type": "Customer",
"role_name": "customer_billing",
"verified": 1,
"sumsub_id": "sum_123456",
"sumsub_comment": null,
"corporate": 0,
"default_lang": "en",
"private_ranges": [
"10.0.0.0/24"
],
"private_vlans": [],
"billing_options": {
"url": "https://billing.example.com",
"location": "NL",
"company": "Example Hosting",
"active": 1,
"allowed_payments": "paypal,stripe",
"native_endpoint": "billing.example.com",
"sumsub_kyc": 1,
"paypal_id": "paypal_id_123"
},
"client_ip": "192.168.1.1",
"timing": {
"auth_validate_token": 0.05,
"auth_tags": 0.02,
"auth_get_role": 0.01
},
"permissions": [
"server/list",
"server/info",
"invoice/list"
],
"billing_servers": [],
"deploy_keys": {},
"has_product_subscription": false,
"prebill_pending": []
}
}

Failure response

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

```

auth/login¶

Returns an access token for the API based on the provided client API key. Checks key validity, access rights, and IP address binding.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `login`
key	✅	string	Client API key for authentication
ttl	❌	int	Token lifetime in seconds (default 3600)

Example Request

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

Example of a successful response

{
"result": {
"token": "string",
"role": "string",
"role_type": "string",
"whmcs_id": 12345,
"whmcs_location": "string",
"servers": [
101,
102
],
"invapi": "string",
"customer_id": 54321,
"permissions": [
"string"
],
"token_expire": 1715000000,
"new": 1,
"prebill": 0
}
}

Failure response

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

auth/logout¶

Clears the access token and terminates the current user session.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `logout`
token	✅	string	Access token to be removed.

Example Request

curl -s "https://invapi.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¶

Forcefully terminates all active user sessions by email and reset token, clears associated tags, and redirects to the login page.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `session_reset`
user_email	✅	string	User email for which sessions are being reset.
reset_token	✅	string	Reset token received earlier (e.g., in a link from email).
confirm	❌	int	Confirmation flag (1). If not passed or equal to 0, an HTML confirmation form is returned.

Example Request

curl -s "https://invapi.hostkey.com/auth.php" -X POST \
--data "action=session_reset" \
--data "user_email=VALUE" \
--data "reset_token=VALUE"

Example of a successful response

{
"redirect": true,
"message": "Sessions successfully reset, redirecting to login page."
}

Failure response

{
"code": -2,
"message": "Invalid reset token or email not found"
}

auth/set_tag¶

Sets or removes the specified tag for the current authenticated user. Available only for administrators or for clients to set the 'auto_credit' tag.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `set_tag`
token	✅	string	User authentication token
tag	✅	string	Tag name (max 32 characters). Only 'auto_credit' is allowed for clients.
set	✅	string	Action flag: if set (not empty), the tag is created; if empty — the tag is removed.

Example Request

curl -s "https://invapi.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¶

Links the specified Telegram username to the current user's account and returns a link to the notification bot.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `tg_verify`
token	✅	string	User authentication token
tg_username	✅	string	Telegram username to link

Example Request

curl -s "https://invapi.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/HostKeyNotifyBot"
}

Failure response

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

auth/vk_init¶

Generates parameters to start the OAuth authorization process via VKontakte (client_id, redirect_uri, code_challenge, device_id, state) and saves the verification code to the database.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `vk_init`
token	❌	string	Current user authorization token (optional, for linking SSO to an existing account)

Example Request

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

Example of a successful response

{
"result": "OK",
"data": {
"client_id": "string",
"redirect_uri": "string",
"code_challenge": "string",
"device_id": "string",
"state": "string"
}
}

Failure response

{
"code": -2,
"message": "auth: malformed request #1"
}

auth/vk_signin¶

Handles the callback from VK ID after authorization. Exchanges the code for a token, checks state and code_verifier, links the VK account to the platform user, or redirects to the login page with an SSO hash.

HTTP Method: GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `vk_signin`
code	✅	string	Authorization code received from VK ID
state	✅	string	Session state containing session ID and random string
device_id	✅	string	Device identifier passed during initialization
token	❌	string	API authentication token (optional, for linking the account)

Example Request

curl -s "https://invapi.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": "redirect",
"action": "vk_signin",
"note": "The method ends with a redirect (header Location) or an error. No JSON response is returned on success."
}

Failure response

``` { "code": "error", "message": "Invalid host header", "details": "Host header validation error" }

```

auth/whmcslogin¶

Logs into the system using WHMCS credentials (email/password) or SSO. Returns an access token, role information, access rights, and client details. Supports login via SSO (Google, VK) and standard authentication.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `whmcslogin`
user	❌	string	User email for login (required if SSO is not used)
password	❌	string	User password (required if SSO is not used)
sso	❌	string	SSO provider identifier (e.g., 'google', 'vk')
sso_hash	❌	string	Hash for SSO session verification
location	❌	string	Billing location (e.g., 'EU', 'US'). If not specified or 'Auto', the system will choose automatically.
fix_ip	❌	integer	Fix token to IP address (1 or 0). Default is 1.
ttl	❌	integer	Token lifetime in seconds. Default is 86400.
customer_data	❌	string	Flag to get full client data (1). Default is empty string.
VisitorID	❌	string	Visitor identifier for analytics.
apikey	❌	string	API key (used for 2FA check).

Example Request

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

Example of a successful response

{
"result": {
"token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"role": "customer_billing",
"role_type": "Customer",
"whmcs_id": 12345,
"whmcs_location": "EU",
"whmcs_token": "",
"permissions": [
"eq/list",
"eq/show",
"billing/invoices"
],
"corporate": 0,
"verified": "pending",
"token_expire": 1715623200,
"new": 1,
"country": "Netherlands",
"country_code": "NL",
"currency_code": "EUR",
"vat": "NL123456789B01",
"VisitorID": "visitor_abc123",
"prebill": 0,
"billing_options": {
"location": "EU",
"company": "HostKey EU",
"active": 1,
"allowed_payments": "paypal,stripe",
"native_endpoint": "billing.hostkey.eu",
"sumsub_kyc": 1
},
"2fa": "email",
"code": "123456"
},
"tags": [
{
"tag": "role_id",
"value": "6",
"extra": "whmcs_login:221 123456"
},
{
"tag": "email",
"value": "[email protected]",
"extra": ""
},
{
"tag": "whmcs_id",
"value": "12345",
"extra": ""
},
{
"tag": "whmcs_location",
"value": "EU",
"extra": "whmcs_login:241 123456"
}
]
}

Failure response

``` { "code": -2, "message": "auth: empty username", "details": { "error_codes": [ "auth: invalid service", "auth: SSO not set", "auth: SSO invalid", "auth: no such user", "auth: empty password", "auth: invalid username", "auth: unable to load billing data, please try again", "auth: unable to load whmcs_get_client, please try again", "auth: unable to find billing contacts data for user, please try again", "auth: ACL violation for user, IP not in the list", "auth: your account suspended for suspected payment fraud", "auth: your account suspended for suspected abuse", "auth: unable to create auth for a user, please try again", "selected SSO linked to user from another billing", "No billing services available! Please check platform configuration!", "This billing service can not be used at the moment, try selecting a different billing", "Authorization failed, please contact support", "Provided user:password combination do not match an existing user", "Unable to authenticate using provided credentials", "auth: unable to clean old metadata, please contact support" ] } }