auth.php¶

Модуль аутентификации и авторизации: управление сессиями, вход через WHMCS, LDAP, API-ключи и SSO (Google, GitHub, VK), верификация 2FA, SMS и email, а также управление тегами клиентов.

Методы API¶

Метод	Действие	Описание
`2fa_check`	проверка 2FA	Валидирует код двухфакторной аутентификации для текущей сессии пользователя.
`2fa_resend`	повторная отправка 2FA	Отправляет повторный код двухфакторной аутентификации (2FA) для текущей сессии пользователя.
`billing_list`	получение списка биллингов	Возвращает список доступных платежных систем (биллингов) для текущего пользователя или все доступные системы, если запрос от администратора.
`email_check`	проверка email	Проверяет существование пользователя по email в указанной локации биллинга. Если пользователь не найден, создается новый аккаунт. Отправляет код верификации на почту.
`flip_tag`	переключение тега	Переключает состояние тега для клиента (если тег существует — удаляет, если нет — создает). Позволяет управлять метаданными пользователя.
`get_log`	получение лога авторизации	Возвращает лог событий авторизации за указанный период или по токену.
`get_log_details`	получение деталей лога	Возвращает подробную информацию о событиях аутентификации по токену пользователя
`github_init`	инициализация GitHub SSO	Инициирует процесс авторизации через GitHub, генерирует уникальный state и возвращает данные клиента для перенаправления пользователя на GitHub.
`github_signin`	авторизация через GitHub	Инициирует процесс авторизации через GitHub. Генерирует временный state и токен для последующего обмена кода на сессию.
`google_signin`	авторизация через Google SSO	Выполняет авторизацию пользователя с использованием Google ID Token. Если токен валиден, привязывает аккаунт к текущей сессии или обновляет связь.
`info`	получение информации о токене	Возвращает подробную информацию о текущей сессии пользователя, включая роль, права доступа (permissions), данные клиента и список доступных серверов.
`ipalogin`	вход через LDAP (IPA)	Авторизация сотрудника через LDAP (IPA) с возможностью привязки к серверу.
`login`	авторизация по API-ключу	Авторизует пользователя через предоставленный API-ключ, устанавливает сессию и возвращает данные о правах доступа, серверах и параметрах клиента.
`logout`	выход из системы	Очищает текущий токен доступа, завершая сессию пользователя.
`session_reset`	сброс сессии	Завершает все активные сессии пользователя, соответствующие предоставленному токену сброса для указанного email.
`set_tag`	управление тегами пользователя	Создает или удаляет тег у клиента. Позволяет управлять метаданными (например, auto_credit) и привязывать дополнительные данные к аккаунту.
`tg_verify`	верификация Telegram username	Привязывает Telegram username пользователя к его аккаунту и возвращает ссылку на бота для уведомлений.
`vk_init`	инициализация авторизации через VK	Инициирует процесс OAuth-авторизации через VK, генерируя временные данные для обмена (code_challenge, state и device_id).
`vk_signin`	авторизация через VK	Инициирует процесс авторизации пользователя через социальную сеть ВКонтакте. Создает временные данные для OAuth-процесса и перенаправляет на страницу авторизации VK.
`whmcslogin`	авторизация через WHMCS	Выполняет вход в систему, используя учетные данные пользователя (email/password) или SSO-метод. Поддерживает проверку 2FA и автоматическое создание сессии.

auth/2fa_check¶

Валидирует код двухфакторной аутентификации для текущей сессии пользователя.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
token	✅	string	Токен авторизации
code	❌	string	Код двухфакторной аутентификации (передается в массиве)

Пример запроса

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

Пример успешного ответа

{
"result": "2FA OK"
}

Примеры ошибок

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

```

auth/2fa_resend¶

Отправляет повторный код двухфакторной аутентификации (2FA) для текущей сессии пользователя.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `2fa_resend`
token	✅	string	Токен авторизации сессии
from	❌	string	Источник запроса (user_profile или resend_dialog)

Пример запроса

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

Пример успешного ответа

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

Примеры ошибок

``` { "code": -1, "message": "Unable to load authentication data, please try again" }

```

auth/billing_list¶

Возвращает список доступных платежных систем (биллингов) для текущего пользователя или все доступные системы, если запрос от администратора.

HTTP-метод: POST|GET

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `billing_list`
token	❌	string	Токен авторизации для проверки прав доступа пользователя к конкретному биллингу

Пример запроса

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

Пример успешного ответа

{
"result": "OK",
"billings": [
{
"billing": "whmcs",
"company": "HostKey WHMCS",
"active": 1,
"native_endpoint": "https://billing.hostkey.com/clientarea.php"
}
]
}

Примеры ошибок

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

```

auth/email_check¶

Проверяет существование пользователя по email в указанной локации биллинга. Если пользователь не найден, создается новый аккаунт. Отправляет код верификации на почту.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `email_check`
user_email	✅	string	Email пользователя (например, `user@example.com`)
location	✅	string	Локация биллинга (например, `whmcs`)
user_token	❌	string	Token for verification code validation

Пример запроса

curl -s "https://invapi.hostkey.ru/auth.php" -X POST \
--data "action=email_check" \
--data "user_email=user@example.com" \
--data "location=whmcs"

Пример успешного ответа

{
"result": "OK",
"state": "verified",
"status": "Email address user@example.com is now verified."
}

Примеры ошибок

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

```

auth/flip_tag¶

Переключает состояние тега для клиента (если тег существует — удаляет, если нет — создает). Позволяет управлять метаданными пользователя.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
token	✅	string	Токен авторизации сессии
tag	✅	string	Имя тега для переключения (максимум 32 символа)

Пример запроса

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

Пример успешного ответа

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

Примеры ошибок

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

```

auth/get_log¶

Возвращает лог событий авторизации за указанный период или по токену.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `get_log`
token	✅	string	Токен сессии
user_token	❌	string	Токен пользователя для поиска лога
period_start	❌	string	Начало периода (YYYY-MM-DD)
period_stop	❌	string	Конец периода (YYYY-MM-DD)
user_email	❌	string	Email пользователя для фильтрации лога

Пример запроса

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

Пример успешного ответа

{
"result": "OK",
"data": [
{
"id": 123,
"action": "login",
"ip": "1.2.3.4",
"time": "2024-01-15 10:00:00"
}
]
}

Примеры ошибок

{
"code": 404,
"message": "Log is empty"
}

auth/get_log_details¶

Возвращает подробную информацию о событиях аутентификации по токену пользователя

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
token	✅	string	Токен сессии для доступа к логам
user_token	❌	string	Дополнительный токен пользователя для получения детального лога

Пример запроса

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

Пример успешного ответа

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

Примеры ошибок

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

```

auth/github_init¶

Инициирует процесс авторизации через GitHub, генерирует уникальный state и возвращает данные клиента для перенаправления пользователя на GitHub.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `github_init`
token	❌	string	Существующий токен сессии (если есть)

Пример запроса

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

Пример успешного ответа

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

Примеры ошибок

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

```

auth/github_signin¶

Инициирует процесс авторизации через GitHub. Генерирует временный state и токен для последующего обмена кода на сессию.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `github_signin`
state	✅	string	Содержит уникальный идентификатор состояния (последние 6 символов — ID сессии)
token	❌	string	Существующий токен пользователя для привязки GitHub к аккаунту
code	✅	string	Параметр `code` (обнаружен в коде)

Пример запроса

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

Пример успешного ответа

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

Примеры ошибок

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

```

auth/google_signin¶

Выполняет авторизацию пользователя с использованием Google ID Token. Если токен валиден, привязывает аккаунт к текущей сессии или обновляет связь.

HTTP-метод: POST|GET

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `google_signin`
credential	✅	string	Google ID Token (JWT) для верификации пользователя
token	❌	string	Текущий токен сессии для привязки Google аккаунта к существующему профилю

Пример запроса

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

Пример успешного ответа

{
"result": "OK",
"sso": "google",
"sso_hash": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"error_code": null,
"sso_set": 0
}

Примеры ошибок

``` { "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¶

Возвращает подробную информацию о текущей сессии пользователя, включая роль, права доступа (permissions), данные клиента и список доступных серверов.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
token	✅	string	Токен авторизации сессии

Пример запроса

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

Пример успешного ответа

{
"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": "user@example.com",
"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": []
}

Примеры ошибок

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

```

auth/login¶

Авторизует пользователя через предоставленный API-ключ, устанавливает сессию и возвращает данные о правах доступа, серверах и параметрах клиента.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
key	✅	string	API-ключ пользователя для авторизации
ttl	❌	integer	Время жизни токена в секундах (по умолчанию 3600)

Пример запроса

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

Пример успешного ответа

{
"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": "Russia",
"country_code": "RU",
"currency_code": "RUB",
"vat": "",
"VisitorID": null,
"billing_options": {}
}

Примеры ошибок

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

```

auth/logout¶

Очищает текущий токен доступа, завершая сессию пользователя.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
token	✅	string	Токен авторизации для удаления сессии

Пример запроса

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

Пример успешного ответа

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

Примеры ошибок

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

```

auth/session_reset¶

Завершает все активные сессии пользователя, соответствующие предоставленному токену сброса для указанного email.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `session_reset`
confirm	❌	integer	Флаг подтверждения действия (1 для выполнения)
user_email	✅	string	Email пользователя для сброса сессий
reset_token	✅	string	Токен сброса (первые 3 и последние 3 символа от login token)

Пример запроса

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

Пример успешного ответа

{
"result": "OK"
}

Примеры ошибок

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

```

auth/set_tag¶

Создает или удаляет тег у клиента. Позволяет управлять метаданными (например, auto_credit) и привязывать дополнительные данные к аккаунту.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `set_tag`
tag	✅	string	Имя тега (максимум 32 символа). Для клиентов разрешен только 'auto_credit'.
set	✅	boolean	Флаг операции: 1 — создать/установить тег, 0 — удалить тег.
token	✅	string	API-токен аутентификации

Пример запроса

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

Пример успешного ответа

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

Примеры ошибок

`` { "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¶

Привязывает Telegram username пользователя к его аккаунту и возвращает ссылку на бота для уведомлений.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `tg_verify`
token	✅	string	Токен авторизации сессии
tg_username	✅	string	Telegram username пользователя (без @ и ссылок)

Пример запроса

curl -s "https://invapi.hostkey.ru/auth.php" -X POST \
--data "action=tg_verify" \
--data "token=HOSTKEY_TOKEN" \
--data "tg_username=VALUE"

Пример успешного ответа

{
"result": "OK",
"bot_url": "https://t.me/your_bot"
}

Примеры ошибок

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

```

auth/vk_init¶

Инициирует процесс OAuth-авторизации через VK, генерируя временные данные для обмена (code_challenge, state и device_id).

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `vk_init`
token	❌	string	Существующий токен сессии (если есть)
state	✅	string	Параметр state для защиты от CSRF

Пример запроса

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

Пример успешного ответа

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

Примеры ошибок

``` { "result": -1, "error": "Ошибка инициализации VK", "code": "VK_INIT_ERROR" }

```

auth/vk_signin¶

Инициирует процесс авторизации пользователя через социальную сеть ВКонтакте. Создает временные данные для OAuth-процесса и перенаправляет на страницу авторизации VK.

HTTP-метод: GET

Параметры:

Параметр	Обязательный	Тип	Описание
state	✅	string	Состояние (state) для защиты от CSRF-атак. Содержит случайный идентификатор и 6 последних символов ID сессии.
code	✅	string	Код авторизации, полученный от VK после успешного подтверждения пользователем.
device_id	❌	string	Идентификатор устройства пользователя.
token	✅	string	API-токен аутентификации

Пример запроса

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

Пример успешного ответа

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

Примеры ошибок

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

```

auth/whmcslogin¶

Выполняет вход в систему, используя учетные данные пользователя (email/password) или SSO-метод. Поддерживает проверку 2FA и автоматическое создание сессии.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `whmcslogin`
token	✅	string	Токен авторизации для проверки сессии
user	✅	string	Email пользователя для входа (используется при обычном логине)
password	✅	string	Пароль пользователя
sso	❌	string	Метод SSO (google, github, vk)
sso_hash	❌	string	Хеш/токен для SSO авторизации
location	❌	string	Конкретный биллинг (WHMCS location)
fix_ip	❌	integer	Привязка токена к IP
ttl	❌	integer	Время жизни токена в секундах

Пример запроса

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

Пример успешного ответа

{
"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": "user@example.com",
"countrycode": "US",
"currency_code": "USD"
},
"billing_options": {},
"corporate": 0,
"verified": null,
"client_ip": "127.0.0.1",
"timing": []
}

Примеры ошибок

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

```