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	Validates the two-factor authentication code for the current user session.
`2fa_resend`	resend 2FA	Resends the two-factor authentication (2FA) code for the current user session.
`billing_list`	get billing list	Returns a list of available payment systems (billings) for the current user or all available systems if the request is from an administrator.
`email_check`	check email	Checks the existence of a user by email in the specified billing location. If the user is not found, a new account is created. Sends a verification code to the email.
`flip_tag`	toggle tag	Toggles the state of a tag for a customer (removes it if the tag exists, creates it if it does not). Allows managing user metadata.
`get_log`	get authorization log	Returns an authorization event log for a specified period or by token.
`get_log_details`	get log details	Returns detailed information about authentication events by user token.
`github_init`	initialize GitHub SSO	Initiates the authorization process via GitHub, generates a unique state, and returns client data to redirect the user to GitHub.
`github_signin`	authorize via GitHub	Initiates the authorization process via GitHub. Generates a temporary state and token for subsequent code-to-session exchange.
`google_signin`	authorize via Google SSO	Performs user authorization using a Google ID Token. If the token is valid, it links the account to the current session or updates the connection.
`info`	get token information	Returns detailed information about the current user session, including role, permissions, client data, and a list of available servers.
`ipalogin`	login via LDAP (IPA)	Employee authorization via LDAP (IPA) with the option to link to a server.
`login`	authorize by API key	Authorizes a user via the provided API key, establishes a session, and returns data regarding permissions, servers, and client parameters.
`logout`	logout from system	Clears the current access token, terminating the user session.
`session_reset`	reset session	Terminates all active user sessions corresponding to the provided reset token for the specified email.
`set_tag`	manage user tags	Creates or deletes a tag for a customer. Allows managing metadata (e.g., auto_credit) and attaching additional data to the account.
`tg_verify`	verify Telegram username	Links a user's Telegram username to their account and returns a link to the bot for notifications.
`vk_init`	initialize VK authorization	Initiates the OAuth authorization process via VK, generating temporary data for exchange (code_challenge, state, and device_id).
`vk_signin`	authorize via VK	Initiates the user authorization process through the VKontakte social network. Creates temporary data for the OAuth process and redirects to the VK authorization page.
`whmcslogin`	authorize via WHMCS	Performs system login using user credentials (email/password) or an SSO method. Supports 2FA verification and automatic session creation.

auth/2fa_check¶

Validates the two-factor authentication code for the current user session.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
token	✅	string	Authorization token
code	❌	string	Two-factor authentication code (passed in an array)

Example Request

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

Example of a successful response

{
"result": "2FA OK"
}

Failure response

``` { "code": -1, "message": "Access denied by IP restrictions" }

```

auth/2fa_resend¶

Resends the two-factor authentication (2FA) code for the current user session.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `2fa_resend`
token	✅	string	Session authorization token
from	❌	string	Request source (user_profile or resend_dialog)

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": -1, "message": "Unable to load authentication data, please try again" }

```

auth/billing_list¶

Returns a list of available payment systems (billings) for the current user or all available systems if the request is from an administrator.

HTTP Method: POST|GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `billing_list`
token	❌	string	Authorization token to verify user access rights to a specific billing

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,
"native_endpoint": "https://billing.hostkey.com/clientarea.php"
}
]
}

Failure response

``` { "code": -2, "message": "Malformed request" }

```

auth/email_check¶

Checks the existence of a user by email in the specified billing location. If the user is not found, a new account is created. Sends a verification code to the email.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `email_check`
user_email	✅	string	User email (e.g., `[email protected]`)
location	✅	string	Billing location (e.g., `whmcs`)
user_token	❌	string	Token for verification code validation

Example Request

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

Example of a successful response

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

Failure response

``` { "code": 0, "message": "Invalid email or billing location error" }

```

auth/flip_tag¶

Toggles the state of a tag for a customer (removes it if the tag exists, creates it if it does not). Allows managing user metadata.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
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 "token=HOSTKEY_TOKEN" \
--data "tag=example_tag"

Example of a successful response

{
"result": "OK",
"message": "auth/flip_tag: tag example removed",
"action": "removed"
}

Failure response

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

```

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	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://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 by user token.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
token	✅	string	Session token for log access
user_token	❌	string	Additional user token to obtain detailed log

Example Request

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

Example of a successful response

{
"result": "OK",
"log": {
"id": 12345,
"event": "login_success",
"timestamp": "2024-05-20T10:30:00Z",
"ip": "192.168.1.1",
"details": {
"user_agent": "Mozilla/5.0...",
"method": "password"
}
}
}

Failure response

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

```

auth/github_init¶

Initiates the authorization process via GitHub, generates a unique state, and returns client data to redirect the user to GitHub.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `github_init`
token	❌	string	Existing session token (if any)

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",
"state": "string"
},
"error_code": null
}

Failure response

``` { "code": -1, "message": "sso_github_unavailable" }

```

auth/github_signin¶

Initiates the authorization process via GitHub. Generates a temporary state and token for subsequent code-to-session exchange.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `github_signin`
state	✅	string	Contains the unique state identifier (last 6 characters are the session ID)
token	❌	string	Existing user token to link GitHub to the account
code	✅	string	The `code` parameter (detected in code)

Example Request

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

Example of a successful response

{
"result": "OK",
"action": "github_signin",
"data": {
"client_id": "string",
"redirect_uri": "string",
"state": "string"
}
}

Failure response

``` { "code": -3, "message": "sso_github_unavailable" }

```

auth/google_signin¶

Performs user authorization using a Google ID Token. If the token is valid, it links the account to the current session or updates the connection.

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": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"error_code": null,
"sso_set": 0
}

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" }, "TAG_RETRIEVAL_ERROR": { "result": "error", "message": "Unable to load authentication data, please try again", "error_code": "TAG_RETRIEVAL_ERROR" } }

```

auth/info¶

Returns detailed information about the current user session, including role, permissions, client data, and a list of available 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": "US",
"servers": [
101,
102
],
"customer_id": 5678,
"permissions": [
"manage_products",
"show_invoices",
"edit_master_profile"
],
"token_expire": 1735689600,
"new": 1,
"prebill": 0,
"email": "[email protected]",
"client_ip": "192.168.1.1",
"timing": {
"auth_validate_token": 5,
"auth_get_role": 2,
"list_permissions": 1
},
"billing_servers": [],
"deploy_keys": {},
"has_product_subscription": false,
"private_ranges": [],
"private_vlans": [],
"verified": null,
"sumsub_id": null,
"sumsub_comment": null,
"corporate": 0,
"tags": [],
"default_lang": "en",
"billing_options": []
}

Failure response

``` { "code": -2, "message": "Invalid token" }

```

auth/login¶

Authorizes a user via the provided API key, establishes a session, and returns data regarding permissions, servers, and client parameters.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
key	✅	string	User's API key for authorization
ttl	❌	integer	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

{
"token": "7bc29eb23fb1b879b21fce509597f07c",
"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": 1715432400,
"new": 1,
"prebill": 0,
"country": "United States",
"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, terminating the user session.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
token	✅	string	Authorization token for session removal

Example Request

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

Example of a successful response

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

Failure response

``` { "code": -2, "message": "Token is not specified" }

```

auth/session_reset¶

Terminates all active user sessions corresponding to the provided reset token for the specified email.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `session_reset`
confirm	❌	integer	Action confirmation flag (1 to execute)
user_email	✅	string	User email for session reset
reset_token	✅	string	Reset token (first 3 and last 3 characters of the login token)

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

{
"result": "OK"
}

Failure response

``` { "code": -2, "message": "Malformed request" }

```

auth/set_tag¶

Creates or deletes a tag for a customer. Allows managing metadata (e.g., auto_credit) and attaching additional data to the account.

HTTP Method: POST

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	Operation flag: 1 — create/set tag, 0 — delete tag.
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 set created/removed",
"action": "set/unset",
"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 were found" } }

```

auth/tg_verify¶

Links a 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	Session authorization token
tg_username	✅	string	User's Telegram username (without @ and links)

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

Failure response

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

```

auth/vk_init¶

Initiates the OAuth authorization process via VK, generating temporary data for exchange (code_challenge, state, and device_id).

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `vk_init`
token	❌	string	Existing session token (if any)
state	✅	string	The `state` parameter for CSRF protection

Example Request

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

Example of a successful response

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

Failure response

``` { "result": -1, "error": "VK initialization error", "code": "VK_INIT_ERROR" }

```

auth/vk_signin¶

Initiates the user authorization process through the VKontakte social network. Creates temporary data for the OAuth process and redirects to the VK authorization page.

HTTP Method: GET

Parameters:

Parameter	Required	Type	Description
state	✅	string	The `state` (state) for CSRF protection. Contains a random identifier and the last 6 characters of the session ID.
code	✅	string	Authorization code received from VK after successful user confirmation.
device_id	❌	string	User's device identifier.
token	✅	string	Authentication API token

Example Request

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

Example of a successful response

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

Failure response

``` { "result": "error", "message": "no state", "error_code": "OAUTH_STATE_MISSING" }

```

auth/whmcslogin¶

Performs system login using user credentials (email/password) or an SSO method. Supports 2FA verification and automatic session creation.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `whmcslogin`
token	✅	string	Authorization token for session verification
user	✅	string	User email for login (used during standard login)
password	✅	string	User password
sso	❌	string	SSO method (google, github, vk)
sso_hash	❌	string	Hash/token for SSO authorization
location	❌	string	Specific billing (WHMCS location)
fix_ip	❌	integer	Token binding to IP
ttl	❌	integer	Token lifetime in seconds

Example Request

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

Example of a successful response

{
"result": "OK",
"module": "auth",
"action": "whmcslogin",
"token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"role": "Customer",
"role_type": "Customer",
"whmcs_id": 123,
"whmcs_location": "US",
"permissions": [
"manage_products",
"show_invoices"
],
"token_expire": 1715864400,
"new": 1,
"country": "United States",
"country_code": "US",
"currency_code": "USD",
"vat": "",
"VisitorID": "v-98765",
"prebill": 0,
"client_data": {
"account_id": 123,
"email": "[email protected]",
"countrycode": "US",
"currency_code": "USD"
},
"billing_options": {},
"corporate": 0,
"verified": null,
"client_ip": "127.0.0.1",
"timing": []
}

Failure response

``` { "code": -3, "message": "sso_google_unavailable" }