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 customer tag management.

API Methods¶

Method	Action	Description
`2fa_check`	check 2FA	Verifies the correctness of the two-factor authentication code for the current user session.
`2fa_resend`	resend 2FA code	Requests a resend of the two-factor authentication code for the user. If the user is in debug mode, the code is returned in the response.
`billing_list`	get list of available billings	Returns a list of available payment systems (billings) available to the current user or administrator.
`email_check`	check email	Verifies email validity, sends a verification code, or checks an existing code/token to confirm the address.
`flip_tag`	toggle tag	Creates or removes the specified tag for the user. If the tag already exists, it will be removed; if it does not exist, it will be created.
`get_log`	get authorization log	Returns an authorization event log for a specified period or by token.
`get_log_details`	get authentication log details	Returns detailed information about authentication events for the current user (via user_token).
`github_init`	initialize GitHub SSO	Returns the data required to initialize authorization via GitHub (`client_id` and `redirect_uri`).
`github_signin`	authorize via GitHub	Exchanges the authorization code for a GitHub access token and links the account to the user (SSO). If the token is already linked, it redirects to an 'already used' page; otherwise, it performs the linking.
`google_signin`	authorize via Google SSO	Logs in using a Google ID Token. If the token is already linked to the user, the method links the current session with this account.
`info`	get token information	Returns detailed information about the current user session, including role, permissions, customer data, and a list of active servers.
`ipalogin`	login via LDAP (IPA)	Employee authorization via LDAP (IPA) with the option to link to a server.
`login`	login via API key	Authorization via client API key. Returns an access token, user role, and a list of available servers.
`logout`	logout from system	Clears the current access token.
`session_reset`	reset session	Terminates all active user sessions corresponding to the provided reset token and clears associated tags.
`set_tag`	manage user tag	Creates or removes a tag for the customer. Allows setting values for specific parameters (e.g., `auto_credit`) or simply toggling the presence of a tag.
`tg_verify`	verify Telegram username	Links the user's Telegram username to their account and returns a link to the bot for notifications.
`vk_init`	initialize VK OAuth	Initiates the authorization process via VK by generating temporary parameters (`code_challenge`, `state`) and saving them for subsequent verification during login.
`vk_signin`	authorize via VK	Performs user authorization via the VK OAuth2 protocol. Exchanges the code for a token and links the account to the user.
`whmcslogin`	user authentication	Logs in using WHMCS credentials (email/password) or SSO (Google). Returns a session token, customer information, permissions, and 2FA status.

auth/2fa_check¶

Verifies the correctness of the two-factor authentication code for the current user session.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
token	✅	string	Access token (from cookie or header)
user_token	✅	string	Two-factor authentication 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": -1, "message": "Authorization error or ACL violation" }

```

auth/2fa_resend¶

Requests a resend of the two-factor authentication code for the user. If the user is in debug mode, the code is returned in the response.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
token	✅	string	User session token
from	❌	string	Request source (`user_profile` or `resend_dialog`)

Example Request

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

Example of a successful response

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

Failure response

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

```

auth/billing_list¶

Returns a list of available payment systems (billings) available to the current user or administrator.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `billing_list`
token	❌	string	Session authorization token

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",
"company": "HostKey WHMCS",
"active": 1,
"allowed_payments": [
"paypal",
"stripe"
],
"native_endpoint": "https://billing.hostkey.com/",
"sumsub_kyc": true
}
]
}

Failure response

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

```

auth/email_check¶

Verifies email validity, sends a verification code, or checks an existing code/token to confirm the address.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
user_email	✅	string	User's email address (e.g., `[email protected]`)
location	✅	string	Country/region code (e.g., `EU`)
user_token	❌	string	Verification code or token for checking an existing code

Example Request

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

Example of a successful response

{
"result": "verified",
"state": "verified",
"status": "Email address [email protected] is now verified."
}

Failure response

``` { "code": -2, "message": "auth/email_check: invalid email user@domain" }

```

auth/flip_tag¶

Creates or removes the specified tag for the user. If the tag already exists, it will be removed; if it does not exist, it will be created.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `flip_tag`
token	✅	string	Session authorization token
tag	✅	string	Tag name to toggle (maximum 32 characters)

Example Request

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

Example of a successful response

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

Failure response

``` { "code": -2, "message": "auth/flip_tag: tag is missing" }

```

auth/get_log¶

Returns an 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	Start of the period (YYYY-MM-DD)
period_stop	❌	string	End of the period (YYYY-MM-DD)
user_email	❌	string	User email for log filtering

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 authentication events for the current user (via user_token).

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_log_details`
token	✅	string	Authentication API token
user_token	✅	string	User token to retrieve log details

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": [
{
"event": "example_event",
"details": "example_detail"
}
]
}

Failure response

``` { "code": 404, "message": "Invalid period or log is empty" }

```

auth/github_init¶

Returns the data required to initialize 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": "GITHUB_CLIENT_ID",
"redirect_uri": "GITHUB_REDIRECT_URI"
},
"error_code": null
}

Failure response

``` {}

```

auth/github_signin¶

Exchanges the authorization code for a GitHub access token and links the account to the user (SSO). If the token is already linked, it redirects to an 'already used' page; otherwise, it performs the linking.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `github_signin`
code	✅	string	Authorization code received from GitHub
state	❌	string	Session state to prevent CSRF attacks (used as a token)

Example Request

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

Example of a successful response

{
"result": "OK",
"sso": "github",
"sso_hash": "abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567",
"error_code": null
}

Failure response

``` { "result": "error", "message": "Authorized, but unable to exchange code for token" }

```

auth/google_signin¶

Logs in using a Google ID Token. If the token is already linked to the user, the method links the current session with this account.

HTTP-method: POST|GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `google_signin`
credential	✅	string	Google ID Token (JWT) for user verification
token	❌	string	Current session token to link the Google account to an 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": "eyJhbGciOiJ...",
"error_code": null,
"sso_set": 1
}

Failure response

``` { "MISSING_CREDENTIAL": { "result": "error", "message": "$module/$action: credential is missing", "error_code": "MISSING_CREDENTIAL" }, "INVALID_CREDENTIAL": { "result": "error", "message": "$module/$action: invalid credential", "error_code": "INVALID_CREDENTIAL" } }

```

auth/info¶

Returns detailed information about the current user session, including role, permissions, customer data, and a list of active servers.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
token	✅	string	Session authorization token

Example Request

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

Example of a successful response

{
"result": "OK",
"role": "Customer",
"role_type": "Customer",
"whmcs_id": 12345,
"whmcs_location": "EU",
"servers": [
101,
102
],
"permissions": [
"manage_products",
"show_invoices",
"edit_master_profile"
],
"token_expire": 1735689600,
"new": 1,
"customer_id": 789,
"email": "[email protected]",
"subaccount": null,
"client_ip": "192.168.1.1",
"timing": [
{
"auth_validate_token": 5
},
{
"auth_get_role": 2
}
]
}

Failure response

{
"code": -2,
"message": "auth: invalid token #13",
"tt": {
"error": "hash without tags found. Stop."
}
}

auth/login¶

Authorization via client API key. Returns an access token, user role, and a list of available servers.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
key	✅	string	Client API key
ttl	❌	int	Token lifetime in seconds (default 3600)
base	❌	string	Base URL for forming `invapi_url`

Example Request

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

Example of a successful response

{
"token": "a1b2c3d4e5f6g7h8i9j0",
"role": "Customer",
"role_type": "Customer",
"whmcs_id": 12345,
"whmcs_location": "US",
"servers": [
101,
102
],
"invapi": "https://invapi.hostkey.com",
"customer_id": 5678,
"permissions": [
"manage_products",
"show_invoices"
],
"token_expire": 1735689600,
"new": 1,
"prebill": 0,
"country": "USA",
"country_code": "US",
"currency_code": "USD",
"vat": "",
"VisitorID": null,
"billing_options": {}
}

Failure response

``` { "code": -1, "message": "No appropriate servers found" }

```

auth/logout¶

Clears the current access token.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `logout`
token	✅	string	Session 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¶

Terminates all active user sessions corresponding to the provided reset token and clears associated tags.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `session_reset`
token	✅	string	Authorization token (used to obtain hash)
user_email	✅	string	User email for session reset
reset_token	✅	string	Special reset token (hash of token + reset_token)
confirm	✅	int	Action confirmation (must be 1)

Example Request

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

Example of a successful response

{
"result": "OK"
}

Failure response

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

```

auth/set_tag¶

Creates or removes a tag for the customer. Allows setting values for specific parameters (e.g., auto_credit) or simply toggling the presence of a tag.

HTTP-method: POST|GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `set_tag`
tag	✅	string	Tag name (maximum 32 characters). For customers, only 'auto_credit' is allowed.
set	✅	boolean	Set value (1) or remove tag (0/null).
token	✅	string	Authentication API token

Example Request

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

Example of a successful response

{
"result": "OK",
"message": "tag created/removed",
"action": "set/unset/absence",
"error_code": null
}

Failure response

`` { "TAG_MISSING": { "code": -2, "message": "$module/$action: tag is missing" }, "VALUE_MISSING": { "code": -2, "message": "$module/$action: set is missing" }, "TAG_TOO_LONG": { "code": -2, "message": "$module/$action: tag too long (32 max)" }, "TAG_INVALID": { "code": -2, "message": "$module/$action: invalid tag (onlyauto_credit` is allowed)" }, "NO_CUSTOMER_ID": { "code": -2, "message": "$module/$action: no customer_id tags was found" } }

```

auth/tg_verify¶

Links the user's Telegram username to their account and returns a link to the bot for notifications.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `tg_verify`
token	✅	string	User authorization token
tg_username	✅	string	Telegram username for verification

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/your_bot_link"
}

Failure response

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

```

auth/vk_init¶

Initiates the authorization process via VK by generating temporary parameters (code_challenge, state) and saving them for subsequent verification during login.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `vk_init`
token	❌	string	Existing session token (if any)
state	❌	string	`state` parameter for request authenticity verification

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_VALUE",
"redirect_uri": "VK_REDIRECT_URI",
"code_challenge": "base64url_encoded_hash",
"device_id": "random_24_chars_string",
"state": "random_30_chars_with_id"
}
}

Failure response

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

```

auth/vk_signin¶

Performs user authorization via the VK OAuth2 protocol. Exchanges the code for a token and links the account to the user.

HTTP-method: GET

Parameters:

Parameter	Required	Type	Description
state	✅	string	`state` received during request initialization. Used for CSRF protection.
code	✅	string	Authorization code received from VK.
device_id	❌	string	Device identifier.

Example Request

curl -s "https://invapi.hostkey.com/auth?action=vk_signin&state=VALUE&code=VALUE" -X GET

Example of a successful response

{
"result": "OK",
"sso": "vk",
"sso_hash": "string"
}

Failure response

``` { "code": -1, "message": "Invalid host header" }

```

auth/whmcslogin¶

Logs in using WHMCS credentials (email/password) or SSO (Google). Returns a session token, customer information, permissions, 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'). If not specified or set to 'Auto', the system will select automatically.
full_customer_data	❌	string	If set to '1', returns complete customer data in the `client_data` field
VisitorID	❌	string	Visitor identifier for analytics/affiliate program
fix_ip	❌	string	Binding 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" }