auth.php¶

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

Методы API¶

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

auth/2fa_check¶

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

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `2fa_check`
token	✅	string	Токен аутентификации, полученный при входе.
user_token	✅	string	Код двухфакторной аутентификации (2FA code).

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

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

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

{
"result": "2FA OK"
}

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

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

auth/2fa_resend¶

Повторно отправляет код двухфакторной аутентификации на привязанный канал связи (email или SMS). Требует валидного токена сессии.

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

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

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

auth/billing_list¶

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

HTTP-метод: POST

Параметры:

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

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

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

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

{
"result": "OK",
"billings": [
{
"location": "NL",
"company": "HostKey Europe",
"url": "https://billing.hostkey.eu",
"admin_url": "https://billing.hostkey.eu/admin",
"active": 1,
"allowed_endpoints": [
"api",
"web"
],
"PAYPAL_ID": "paypal_eu_id_123",
"HTTP_HOST": "billing.hostkey.eu"
}
]
}

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

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

```

auth/email_check¶

Валидация email клиента, отправка кода подтверждения или проверка введенного кода. Используется для верификации адреса электронной почты.

HTTP-метод: POST|GET

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `email_check`
user_email	✅	string	Email address to verify
location	✅	string	Billing location identifier
user_token	❌	string	Verification code received via email

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

curl -s "https://invapi.hostkey.ru/auth.php" -X POST|GET \
--data "action=email_check" \
--data "user_email=VALUE" \
--data "location=VALUE"

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

{
"result": "OK",
"state": "sent",
"smtp": {
"result": "OK",
"message": "Mail sent"
},
"message": "Verification email sent to user@example.com, please confirm in 15 minutes"
}

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

{
"code": -2,
"message": "auth/email_check: invalid email user@example.com"
}

auth/flip_tag¶

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

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `flip_tag`
token	✅	string	Токен аутентификации пользователя
tag	✅	string	Имя тега для переключения (макс. 32 символа). Для клиентов разрешен только 'auto_credit'.

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

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

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

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

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

{
"code": "error",
"message": "auth/flip_tag: tag is missing"
}

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¶

Возвращает подробную информацию о записи лога авторизации по указанному токену пользователя. Требует валидного токена сессии и права доступа auth/get_log.

HTTP-метод: POST

Параметры:

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

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

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

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

{
"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": "2023-10-27T10:30:00Z"
}
}

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

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

```

auth/github_init¶

Возвращает параметры для инициализации процесса авторизации через GitHub (client_id и redirect_uri).

HTTP-метод: POST

Параметры:

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

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

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

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

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

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

{
"code": -1,
"message": "Internal server error"
}

auth/github_signin¶

Завершает процесс авторизации через GitHub OAuth. Обменивает код на токен, получает данные пользователя и привязывает аккаунт GitHub к текущей сессии или создает новую SSO-связь.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `github_signin`
code	✅	string	Код авторизации, полученный от GitHub OAuth
state	❌	string	Токен текущей сессии пользователя (для привязки аккаунта)

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

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

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

{
"redirect": "https://{host}/?sso=github&sso_hash={hash}",
"note": "Метод завершается HTTP-редиректом (header Location). JSON не возвращается."
}

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

{
"code": -1,
"message": "Invalid host header",
"details": {
"error": "Ошибка валидации хоста или обмена кода на токен"
}
}

auth/google_signin¶

Обработка входа через Google SSO. Привязывает аккаунт Google к текущей сессии или возвращает хеш для последующего входа.

HTTP-метод: POST

Параметры:

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

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

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

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

{
"result": "OK",
"sso": "google",
"sso_hash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"error_code": null
}

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

{
"code": -1,
"message": "auth/google_signin: credential is missing",
"error_code": "MISSING_CREDENTIAL"
}

auth/info¶

Возвращает детальную информацию о текущем токене: роль, права доступа, список серверов, статус верификации, настройки биллинга и приватные IP-диапазоны.

HTTP-метод: POST

Параметры:

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

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

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

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

{
"result": {
"servers": [
12345,
67890
],
"show_products": 1,
"manage_products": 1,
"show_invoices": 1,
"manage_orders": 1,
"ipsubnet_announce": 1,
"edit_master_profile": 1,
"email": "user@example.com",
"whmcs_id": 98765,
"whmcs_location": "NL",
"token_expire": 1715623200,
"2fa": "email",
"subaccount": null,
"prebill": 0,
"customer_id": 54321,
"billing_servers": [],
"deploy_keys": {},
"prebill_pending": [],
"has_product_subscription": false,
"permissions": [
"server/list",
"server/info",
"billing/invoices"
],
"role_type": "Customer",
"role_name": "customer_billing",
"verified": 1,
"sumsub_id": "sum_123456",
"sumsub_comment": null,
"private_ranges": [
"10.0.0.0/24"
],
"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_123"
},
"client_ip": "192.168.1.1",
"timing": []
}
}

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

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

```

auth/login¶

Возвращает токен доступа и информацию о клиенте на основе предоставленного API-ключа. Проверяет права доступа, привязку к IP и наличие активных серверов.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `login`
key	✅	string	API-ключ клиента для аутентификации
ttl	❌	int	Время жизни токена в секундах (по умолчанию 3600)
base	❌	string	Базовый URL для invapi (опционально)

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

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

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

{
"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/show",
"billing/invoices"
],
"token_expire": 1715623200,
"new": 1,
"prebill": 0
}
}

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

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

```

auth/logout¶

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

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `logout`
token	✅	string	Токен доступа, который необходимо удалить.

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

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

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

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

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

{
"code": -2,
"message": "auth: no token specified"
}

auth/session_reset¶

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

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `session_reset`
user_email	✅	string	Email пользователя, сессии которого необходимо сбросить.
reset_token	✅	string	Токен сброса, полученный ранее (например, в ссылке из email).
confirm	❌	int	Флаг подтверждения (1). Если не передан или равен 0, возвращается HTML-форма подтверждения.

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

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

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

{
"redirect": true,
"message": "Сессии успешно сброшены, перенаправление на главную страницу."
}

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

{
"code": -2,
"message": "Неверный токен сброса или email не найден"
}

auth/set_tag¶

Устанавливает или удаляет указанный тег для текущего пользователя. Доступен только для администраторов или для тега 'auto_credit' для клиентов.

HTTP-метод: POST

Параметры:

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

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

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

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

{
"result": "OK",
"message": "auth/set_tag: tag auto_credit created",
"action": "set",
"error_code": null
}

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

``` { "code": -1, "message": "auth/set_tag: tag is missing" }

```

auth/tg_verify¶

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

HTTP-метод: POST

Параметры:

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

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

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

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

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

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

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

auth/vk_init¶

Возвращает данные для инициализации OAuth потока с VK ID.

HTTP-метод: POST

Параметры:

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

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

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

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

{
"result": "OK",
"data": {
"client_id": "vk_client_id_from_config",
"redirect_uri": "https://example.com/callback",
"code_challenge": "base64url_encoded_sha256_challenge",
"device_id": "random_device_id_24chars",
"state": "random_state_30chars_id6chars"
}
}

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

{
"code": -1,
"message": "Configuration error or internal server error"
}

auth/vk_signin¶

Обработка колбэка от VK ID после авторизации. Обменивает код на токен, проверяет state и code_verifier, привязывает SSO-хеш к аккаунту клиента или перенаправляет на страницу входа с SSO-параметрами.

HTTP-метод: GET

Параметры:

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

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

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

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

{
"result": "redirect",
"action": "vk_signin",
"data": {
"redirect_url": "https://example.com/?sso=vk&sso_hash=abc123..."
}
}

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

{
"code": -1,
"message": "Invalid host header",
"details": {
"error_code": "INVALID_HOST"
}
}

auth/whmcslogin¶

Выполняет вход в систему с использованием учетных данных WHMCS (email/пароль) или SSO. Возвращает токен сессии, информацию о пользователе, права доступа и статус 2FA.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `whmcslogin`
user	✅	string	Email пользователя для входа (требуется, если не используется SSO)
password	✅	string	Пароль пользователя (требуется, если не используется SSO)
sso	❌	string	Идентификатор SSO провайдера (например, 'google', 'vk'). Если указан, параметры user/password игнорируются.
sso_hash	❌	string	Хеш SSO сессии (требуется, если указан параметр sso)

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

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

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

{
"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": 1,
"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
},
"client_data": {
"id": 12345,
"firstname": "John",
"lastname": "Doe",
"email": "john.doe@example.com",
"phonenumber": "+31612345678",
"address1": "Herengracht 1",
"city": "Amsterdam",
"state": "NH",
"postcode": "1017",
"country": "Netherlands",
"currency": "EUR",
"customfields": [
{
"id": 1,
"name": "INN",
"value": "1234567890"
}
]
}
},
"tags": [
{
"id": 101,
"tag": "role_id",
"value": "6",
"extra": "whmcs_login:221 123456"
},
{
"id": 102,
"tag": "email",
"value": "john.doe@example.com",
"extra": ""
},
{
"id": 103,
"tag": "whmcs_id",
"value": "12345",
"extra": ""
},
{
"id": 104,
"tag": "whmcs_location",
"value": "EU",
"extra": "whmcs_login:241 123456"
},
{
"id": 105,
"tag": "customer_id",
"value": "54321",
"extra": "whmcs_login"
}
]
}

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

``` { "code": -2, "message": "auth: empty username", "details": { "error_codes": [ "auth: invalid service", "auth: SSO not set", "auth: no such user", "auth: empty password", "auth: invalid username", "#109 auth: location authenthication failure: User/password combination not found", "Authorization failed, please contact support", "Unable to authenticate using provided credentials", "auth: unable to load billing data, please try again", "auth: ACL violation for user, IP not in the list", "auth: your account suspened for suspected payment fraud", "auth: your account suspened for suspected abuse" ] } }

```