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 validation	Confirms the two-factor authentication code previously sent to the user. Requires a valid session token.
`2fa_resend`	resend 2FA code	Resends the two-factor authentication code to the linked method (email, sms, app). 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 provided, the list is filtered by the user's or administrator's location.
`email_check`	check email	Validates the client's email, sends a confirmation code, or checks the entered code. Used for email address verification.
`flip_tag`	toggle tag	Toggles the state of the specified tag for the current user. If the tag exists, it is removed. If it does not exist, it is created. Available only for allowed tags (e.g., 'auto_credit' for clients).
`get_log`	get auth log	Returns the authorization event log for the specified period or by token.
`get_log_details`	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.
`github_init`	initialize GitHub login	Returns parameters for initializing OAuth authorization via GitHub (client_id and redirect_uri).
`github_signin`	authorize via GitHub	Processes the callback from GitHub OAuth. Exchanges the code for a token, retrieves user data, checks the SSO hash binding to the account, or redirects to the login page with SSO parameters.
`google_signin`	authenticate via Google SSO	Performs login or links a Google account. If a valid session token is provided, it links the Google ID to the current user. If no token is provided, it returns data for subsequent SSO login.
`info`	get token info	Returns detailed information about the current token: role, access rights, linked servers, verification status, and billing settings.
`ipalogin`	login via LDAP (IPA)	Authorizes an employee via LDAP (IPA) with the option 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 access rights, IP binding, and the presence of active servers.
`logout`	logout	Clears the access token and terminates the current user session.
`session_reset`	reset sessions	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 tag	Sets or removes the specified tag for the current authenticated user. For clients, only the 'auto_credit' tag is allowed.
`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 OAuth2 authorization via VK ID (PKCE flow). Creates a unique session ID, code_verifier, and code_challenge, saves them in tags, and returns data for redirection.
`vk_signin`	complete VK SSO login	Processes the callback from VK OAuth2. Exchanges the code for a token, checks state and code_verifier, links the VK account to the user, or redirects to the login page with an SSO hash.
`whmcslogin`	user authentication	Logs into the system using WHMCS credentials (email/password) or SSO (Google). Returns a session token, client information, access rights, and 2FA status.

auth/2fa_check¶

Confirms the two-factor authentication code previously sent to the user. 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, sms, app). 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 tag 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",
"code": "1234"
}

Failure response

{
"code": -2,
"message": "Invalid token or customer record error"
}

auth/billing_list¶

Returns a list of available billing systems (WHMCS) for the current deployment domain. If a valid token is provided, 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 provided, the billing list is filtered by the user's (or administrator's) location. If not provided, the general list 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": [
{
"billing": "whmcs",
"location": "NL",
"company": "HostKey Europe",
"active": 1,
"allowed_payments": "paypal,stripe",
"native_endpoint": "billing.hostkey.com",
"sumsub_kyc": 1
}
]
}

Failure response

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

```

auth/email_check¶

Validates the client's email, sends a confirmation code, or checks the entered code. Used for email address verification.

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 "[email protected]" \
--data "location=EU-Central"

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": "Fail", "message": "auth/email_check: invalid email user@example.com", "state": "fail", "error": "auth/email_check: invalid email user@example.com" }

```

auth/flip_tag¶

Toggles the state of the specified tag for the current user. If the tag exists, it is removed. If it does not exist, it is created. Available only for allowed tags (e.g., 'auto_credit' for clients).

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 (max. 32 characters). For clients, only 'auto_credit' is allowed.

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 the period (YYYY-MM-DD)
period_stop	❌	string	End of the 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": "2024-05-20T10:30:00Z"
}
]
}

Failure response

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

```

auth/github_init¶

Returns parameters 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": 0,
"message": "No explicit errors defined in code branch"
}

auth/github_signin¶

Processes the callback from GitHub OAuth. Exchanges the code for a token, retrieves user data, checks the SSO hash binding to the account, or redirects to the login page with SSO parameters.

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 (if linking an account)

Example Request

curl -s "https://invapi.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": "Redirect",
"message": "The method ends with a redirect (header Location) to the login page with SSO parameters or confirmation of linking."
}

Failure response

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

auth/google_signin¶

Performs login or links a Google account. If a valid session token is provided, it links the Google ID to the current user. If no token is provided, it returns data for subsequent SSO login.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `google_signin`
credential	✅	string	Google ID token (JWT) obtained from Google Identity Services
token	❌	string	User session token to link Google account to existing profile

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": "string",
"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, linked servers, verification status, and billing settings.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `info`
token	✅	string	Authentication token obtained previously during 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,
"2fa": "email",
"subaccount": null,
"prebill": 0,
"customer_id": 54321,
"billing_servers": [],
"deploy_keys": {},
"prebill_pending": [],
"has_product_subscription": false,
"permissions": [
"eq/list",
"eq/status",
"billing/invoices"
],
"role_type": "Customer",
"role_name": "customer_billing",
"verified": 1,
"sumsub_id": "sum_123456",
"sumsub_comment": null,
"private_ranges": [],
"private_vlans": [],
"default_lang": "en",
"corporate": 0,
"tags": [],
"billing_options": {
"url": "https://billing.example.com",
"location": "NL",
"company": "Hosting Provider",
"active": 1,
"allowed_payments": "paypal,stripe",
"native_endpoint": "billing.example.com",
"sumsub_kyc": 1,
"paypal_id": "paypal_merchant_id"
},
"client_ip": "192.168.1.1",
"timing": []
}
}

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 access rights, IP binding, and the presence of active servers.

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)
base	❌	string	Base URL for invapi (optional)

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": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"role": "customer_billing",
"role_type": "Customer",
"whmcs_id": 12345,
"whmcs_location": "whmcs",
"servers": [
101,
102
],
"invapi": "invapi.hostkey.com",
"customer_id": 54321,
"permissions": [
"eq/list",
"eq/status",
"billing/invoices"
],
"token_expire": 1715623200,
"new": 1,
"prebill": 0
}
}

Failure response

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

```

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 reset.
reset_token	✅	string	Reset token obtained previously (e.g., in a link from email).
confirm	❌	int	Confirmation flag (1). If not provided 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 the main 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. For clients, only the 'auto_credit' tag is allowed.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `set_tag`
token	✅	string	User authentication token
tag	✅	string	Tag name to set or remove (max. 32 characters)
set	✅	string	Action flag: if set — tag is created, if not — 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=example_user"

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 OAuth2 authorization via VK ID (PKCE flow). Creates a unique session ID, code_verifier, and code_challenge, saves them in tags, and returns data for redirection.

HTTP Method: POST

Parameters:

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

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": "VK_CLIENT_ID",
"redirect_uri": "VK_REDIRECT_URI",
"code_challenge": "base64url_encoded_sha256_hash",
"device_id": "random_string_24_chars",
"state": "random_string_30_chars_plus_id"
}
}

Failure response

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

auth/vk_signin¶

Processes the callback from VK OAuth2. Exchanges the code for a token, checks state and code_verifier, links the VK account to the 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 OAuth2
state	✅	string	State parameter for CSRF protection and session ID extraction
device_id	✅	string	Device identifier passed during initialization
token	❌	string	Current user token (if linking VK account to an existing profile)

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",
"data": null,
"note": "The method ends with a call to header('Location: ...') and die(), so no JSON response is formed. An HTTP redirect occurs to the login page with parameters sso=vk&sso_hash=..."
}

Failure response

``` { "code": "error", "message": "Invalid host header", "details": { "error_code": "INVALID_HOST" } }

```

auth/whmcslogin¶

Logs into the system using WHMCS credentials (email/password) or SSO (Google). Returns a session token, client information, access rights, and 2FA status.

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 type (e.g., 'google'). If specified, user/password parameters are ignored.
sso_hash	❌	string	Hash or credential for SSO login (e.g., Google ID token)
location	❌	string	Explicit billing location specification (e.g., 'EU', 'US-East'). If not specified or 'Auto', the system will choose automatically.
full_customer_data	❌	string	If equal to '1', returns full client data in the client_data field
VisitorID	❌	string	Visitor identifier for analytics/affiliate program
fix_ip	❌	string	Bind token to IP (default 1)
ttl	❌	string	Token lifetime in seconds (default 86400)

Example Request

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

Example of a successful response

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

Failure response

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