Skip to content

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 code Resends the two-factor authentication code to the specified method (email or SMS) for the current session.
billing_list get list of available billings Returns a list of available payment systems (billings) linked to the current user or available to the administrator.
email_check check email Checks if a customer exists by email in the specified billing location. If the customer is not found, a new account is created and a verification code is sent to the email.
flip_tag toggle tag Toggles the tag state (creates it if it doesn't exist, or removes it if it exists) for the current user.
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 for a user via their token.
github_init initialize GitHub SSO Initiates the GitHub authorization process, generates a unique state, and returns the data required to redirect the user to the GitHub OAuth page.
github_signin initialize GitHub login Initiates the GitHub OAuth authorization process, generates a temporary state, and saves data for subsequent code exchange.
google_signin authorize via Google SSO Logs in using a Google ID Token. If the token is valid, it links the account to the current session or connects an existing profile.
info get token information Returns detailed information about the current user session, including role, permissions, customer data, and active 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 using the provided API key. Creates a session (hash), sets a token, and returns data regarding permissions, servers, and billing parameters.
logout logout from system Clears the user's active access token, terminating the session.
session_reset reset session Terminates all active user sessions corresponding to the provided reset token and email.
set_tag manage user tag Creates or removes a tag for a customer. For regular users, only management of the auto_credit tag is allowed.
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 VK OAuth authorization process, generates temporary data (code_challenge, state), and saves it in the system for subsequent confirmation.
vk_signin authorize via VK Initiates the user authorization process through the VKontakte social network (VK OAuth2). Returns data to redirect the user to the VK authorization page.
whmcslogin authorize via WHMCS or SSO Logs into the system. Supports standard authorization (email/password) and SSO methods (Google, GitHub, VK). Upon successful login, returns a session token, user data, and permissions.

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 (used in twofa_verify_code)

Example Request

curl -s "https://invapi.hostkey.com/auth.php" -X POST \
--data "token=HOSTKEY_TOKEN"
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 code to the specified method (email or SMS) for the current session.

HTTP Method: POST

Parameters:

Parameter Required Type Description
action ✅ string Method identifier: 2fa_resend
token ✅ string User 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) linked to the current user or available to the administrator.

HTTP Method: POST

Parameters:

Parameter Required Type Description
action ✅ string Method identifier: billing_list
token ❌ string Authorization token for determining access rights (if empty, the list of all billings is available)

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,
"location": "US"
}
]
}
Failure response

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

```

auth/email_check

Checks if a customer exists by email in the specified billing location. If the customer is not found, a new account is created and a verification code is sent 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 Required for verification step

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": 400, "message": "Invalid email or billing location required" }

```

auth/flip_tag

Toggles the tag state (creates it if it doesn't exist, or removes it if it exists) for the current user.

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 (e.g., 'auto_credit')

Example Request

curl -s "https://invapi.hostkey.com/auth.php" -X POST \
--data "action=flip_tag" \
--data "token=HOSTKEY_TOKEN" \
--data "tag=auto_credit"
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: 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 a user via their token.

HTTP Method: POST

Parameters:

Parameter Required Type Description
action ✅ string Method identifier: get_log_details
token ✅ string User session token
user_token ❌ string Additional token to retrieve logs for a specific user

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": 123,
"event": "login_success",
"timestamp": "2024-05-20T10:30:00Z",
"ip": "192.168.1.1",
"details": "User logged in via Google SSO"
}
]
}
Failure response

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

```

auth/github_init

Initiates the GitHub authorization process, generates a unique state, and returns the data required to redirect the user to the GitHub OAuth page.

HTTP Method: POST

Parameters:

Parameter Required Type Description
token ❌ string Session token (optional)

Example Request

curl -s "https://invapi.hostkey.com/auth.php" -X POST \
--data "token=your_session_token"
Example of a successful response 
{
"result": "OK",
"data": {
"client_id": "GITHUB_CLIENT_ID",
"redirect_uri": "GITHUB_REDIRECT_URI",
"state": "string (random state + 6 digits id)"
},
"error_code": null
}
Failure response

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

```

auth/github_signin

Initiates the GitHub OAuth authorization process, generates a temporary state, and saves data for subsequent code exchange.

HTTP Method: POST|GET

Parameters:

Parameter Required Type Description
action ✅ string Method identifier: github_signin
state ✅ string Mandatory parameter (contains session ID)
token ❌ string Existing user token to link the GitHub account to a profile
code ✅ string The code parameter (authorization 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",
"sso": "github",
"sso_hash": "string",
"error_code": null
}
Failure response

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

```

auth/google_signin

Logs in using a Google ID Token. If the token is valid, it links the account to the current session or connects an existing profile.

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

``` { "MISSING_CREDENTIAL": { "result": "error", "message": "\(module/google_signin: credential is missing", "error_code": "MISSING_CREDENTIAL" }, "INVALID_CREDENTIAL": { "result": "error", "message": "\)module/google_signin: invalid credential", "error_code": "INVALID_CREDENTIAL" } }

```

auth/info

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

HTTP Method: POST

Parameters:

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

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": "OK",
"role": "Customer",
"role_name": "Customer",
"role_type": "Customer",
"whmcs_id": 12345,
"whmcs_location": "US",
"servers": [
101,
102
],
"customer_id": 5678,
"permissions": [
"manage_products",
"show_invoices"
],
"token_expire": 1735689600,
"new": 1,
"prebill": true,
"prebill_scope": "all",
"email": "[email protected]",
"client_ip": "192.168.1.1",
"corporate": 0,
"verified": null,
"sumsub_id": null,
"sumsub_comment": null,
"default_lang": "en",
"private_ranges": [],
"private_vlans": [],
"billing_options": {},
"has_product_subscription": false,
"deploy_keys": [],
"prebill_pending": []
}
Failure response

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

```

auth/login

Authorizes a user using the provided API key. Creates a session (hash), sets a token, and returns data regarding permissions, servers, and billing parameters.

HTTP Method: POST

Parameters:

Parameter Required Type Description
key ✅ string User's API key for authorization
ttl ❌ int Token lifetime in seconds (default is 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": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f",
"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": true,
"prebill_scope": "all",
"prebill_global": true,
"country": "USA",
"country_code": "US",
"currency_code": "USD",
"vat": "",
"VisitorID": null,
"client_ip": "127.0.0.1"
}
Failure response

``` { "code": -1, "message": "API key is empty" }

```

auth/logout

Clears the user's active access token, terminating the session.

HTTP Method: POST

Parameters:

Parameter Required Type Description
token ✅ string Active session token to be removed

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 and email.

HTTP Method: POST

Parameters:

Parameter Required Type Description
token ✅ string Authorization token (from global scope)
user_email ✅ string User email for session reset
reset_token ✅ string Special reset token (6 characters: first 3 and last 3 from the login token)
confirm ❌ integer Action confirmation flag (1 to execute)

Example Request

curl -s "https://invapi.hostkey.com/auth.php" -X POST \
--data "token=HOSTKEY_TOKEN" \
--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 removes a tag for a customer. For regular users, only management of the auto_credit tag is allowed.

HTTP Method: POST|GET

Parameters:

Parameter Required Type Description
action ✅ string Method identifier: set_tag
tag ✅ string Tag name (only auto_credit is allowed for customers)
set ✅ boolean Set value (1) or remove tag (0/empty)
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/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": "tag too long (32 max)" }, "TAG_INVALID": { "code": -2, "message": "invalid tag (onlyauto_credit` is allowed)" }, "NO_CUSTOMER_ID": { "code": -2, "message": "no customer_id tags was 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/example_bot"
}
Failure response

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

```

auth/vk_init

Initiates the VK OAuth authorization process, generates temporary data (code_challenge, state), and saves it in the system for subsequent confirmation.

HTTP Method: POST|GET

Parameters:

Parameter Required Type Description
action ✅ string Method identifier: vk_init
token ❌ string Existing session token (if any)
state ✅ string OAuth authorization state parameter

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": -2, "error": "Malformed request", "code": "MALFORMED_REQUEST" }

```

auth/vk_signin

Initiates the user authorization process through the VKontakte social network (VK OAuth2). Returns data to redirect the user to the VK authorization page.

HTTP Method: GET

Parameters:

Parameter Required Type Description
state ✅ string OAuth request state (contains ID for integrity check)
code ✅ string Authorization code received from VK
device_id ❌ string Device identifier
token ✅ string Authentication API token

Example Request

curl -s "https://invapi.hostkey.com/auth.php" -X GET \
--data "state=VALUE" \
--data "code=VALUE" \
--data "token=HOSTKEY_TOKEN"
Example of a successful response 
{
"result": "OK",
"sso": "vk",
"sso_hash": "raw_login_token",
"error_code": null
}
Failure response

``` { "code": 400, "message": "OAUTH_STATE_MISMATCH" }

```

auth/whmcslogin

Logs into the system. Supports standard authorization (email/password) and SSO methods (Google, GitHub, VK). Upon successful login, returns a session token, user data, and permissions.

HTTP Method: POST

Parameters:

Parameter Required Type Description
user ✅ string User email (for standard login)
password ✅ string User password
token ❌ string Authorization token for session verification
sso ❌ string SSO method (google, github, vk)
sso_hash ❌ string Hash or token for SSO authorization

Example Request

curl -s "https://invapi.hostkey.com/auth.php" -X POST \
--data "user=VALUE" \
--data "password=VALUE"
Example of a successful response 
{
"token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0",
"role": "Customer",
"role_type": "Customer",
"whmcs_id": 12345,
"whmcs_location": "US",
"permissions": [
"manage_products",
"show_invoices"
],
"token_expire": 1715865600,
"new": 1,
"country": "USA",
"country_code": "US",
"currency_code": "USD",
"vat": "",
"prebill": true,
"prebill_scope": "all",
"prebill_global": true,
"client_data": {
"account_id": 12345,
"email": "[email protected]",
"countrycode": "US",
"currency_code": "USD"
}
}
Failure response

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

question_mark
Is there anything I can help you with?
question_mark
AI Assistant ×