auth.php¶

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

Методы API¶

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

auth/2fa_check¶

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

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

auth/2fa_resend¶

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

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

auth/billing_list¶

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

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
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",
"location": "NL",
"company": "HostKey Europe",
"active": 1,
"allowed_payments": "paypal,stripe",
"native_endpoint": "billing.hostkey.com",
"sumsub_kyc": 1
}
]
}

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

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

```

auth/email_check¶

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

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `email_check`
user_email	✅	string	Email адрес для проверки или верификации
location	✅	string	Локация биллинга (billing location)
user_token	❌	string	Код подтверждения, отправленный на email

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

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

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

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

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

``` { "code": "Fail", "message": "auth/email_check: invalid email user@example.com", "state": "fail", "error": "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": "2024-05-20T10:30:00Z"
}
]
}

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

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

```

auth/github_init¶

Возвращает параметры для инициализации OAuth-авторизации через 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": 0,
"message": "No explicit errors defined in code branch"
}

auth/github_signin¶

Обработка обратного вызова от GitHub OAuth. Обменивает код на токен, получает данные пользователя, проверяет привязку SSO-хэша к аккаунту или перенаправляет на страницу входа с параметрами 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" \
--data "token=HOSTKEY_TOKEN"

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

{
"result": "Redirect",
"message": "Метод завершается перенаправлением (header Location) на страницу входа с параметрами SSO или подтверждением привязки."
}

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

{
"code": -1,
"message": "Invalid host header",
"details": "Ошибка валидации заголовка Host"
}

auth/google_signin¶

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

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `google_signin`
credential	✅	string	Google ID token (JWT) obtained from Google Identity Services
token	❌	string	User session token to link Google account to existing profile

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

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

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

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

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

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

auth/info¶

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

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": 1715000000,
"2fa": "email",
"subaccount": null,
"prebill": 0,
"customer_id": 54321,
"billing_servers": [],
"deploy_keys": {},
"prebill_pending": [],
"has_product_subscription": false,
"permissions": [
"eq/list",
"eq/status",
"billing/invoices"
],
"role_type": "Customer",
"role_name": "customer_billing",
"verified": 1,
"sumsub_id": "sum_123456",
"sumsub_comment": null,
"private_ranges": [],
"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_merchant_id"
},
"client_ip": "192.168.1.1",
"timing": []
}
}

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

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

```

auth/login¶

Возвращает токен доступа для API на основе предоставленного 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/status",
"billing/invoices"
],
"token_expire": 1715623200,
"new": 1,
"prebill": 0
}
}

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

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

```

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 символа)
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¶

Генерирует параметры для начала OAuth2-авторизации через VK ID (PKCE flow). Создает уникальный ID сессии, code_verifier и code_challenge, сохраняет их в тегах и возвращает данные для редиректа.

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",
"redirect_uri": "VK_REDIRECT_URI",
"code_challenge": "base64url_encoded_sha256_hash",
"device_id": "random_string_24_chars",
"state": "random_string_30_chars_plus_id"
}
}

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

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

auth/vk_signin¶

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

HTTP-метод: GET

Параметры:

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

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

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

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

{
"result": "redirect",
"action": "vk_signin",
"data": null,
"note": "Метод завершается вызовом header('Location: ...') и die(), поэтому JSON-ответ не формируется. Происходит HTTP-редирект на страницу входа с параметрами sso=vk&sso_hash=..."
}

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

``` { "code": "error", "message": "Invalid host header", "details": { "error_code": "INVALID_HOST" } }

```

auth/whmcslogin¶

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

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `whmcslogin`
user	❌	string	Email пользователя для входа (требуется, если не используется SSO)
password	❌	string	Пароль пользователя (требуется, если не используется SSO)
sso	❌	string	Тип SSO провайдера (например, 'google'). Если указан, параметры user/password игнорируются.
sso_hash	❌	string	Хеш или credential для SSO входа (например, Google ID token)
location	❌	string	Явное указание локации биллинга (например, 'EU', 'RU'). Если не указано или 'Auto', система выберет автоматически.
full_customer_data	❌	string	Если равно '1', возвращает полные данные клиента в поле client_data
VisitorID	❌	string	Идентификатор посетителя для аналитики/партнерской программы
fix_ip	❌	string	Привязка токена к IP (по умолчанию 1)
ttl	❌	string	Время жизни токена в секундах (по умолчанию 86400)

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

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

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

{
"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": "user@example.com",
"extra": ""
},
{
"id": 3,
"tag": "whmcs_id",
"value": "12345",
"extra": ""
},
{
"id": 4,
"tag": "whmcs_location",
"value": "EU",
"extra": "whmcs_login:241 123456"
}
]
}

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

``` { "code": -2, "message": "auth: empty username" }

```