auth.php¶

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

Методы API¶

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

auth/2fa_check¶

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

HTTP-метод: POST

Параметры:

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

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

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": -1, "message": "Ошибка авторизации или ACL нарушение" }

```

auth/2fa_resend¶

Запрашивает повторную отправку кода двухфакторной аутентификации для пользователя. Если пользователь находится в режиме отладки, код возвращается в ответе.

HTTP-метод: POST

Параметры:

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

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

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

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

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

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

``` { "code": -1, "message": "Invalid customer record" }

```

auth/billing_list¶

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

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",
"company": "HostKey WHMCS",
"active": 1,
"allowed_payments": [
"paypal",
"stripe"
],
"native_endpoint": "https://billing.hostkey.com/",
"sumsub_kyc": true
}
]
}

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

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

```

auth/email_check¶

Проверяет валидность email, отправляет код верификации или проверяет уже существующий код/токен для подтверждения адреса.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
user_email	✅	string	Email адрес пользователя (например, `user@example.com`)
location	✅	string	Код страны/региона (например, `RU`)
user_token	❌	string	Код верификации или токен для проверки уже существующего кода

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

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

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

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

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

``` { "code": -2, "message": "auth/email_check: invalid email user@domain" }

```

auth/flip_tag¶

Создает или удаляет указанный тег у пользователя. Если тег уже существует, он будет удален; если не существует — создан.

HTTP-метод: POST

Параметры:

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

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

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

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

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

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

``` { "code": -2, "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¶

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

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `get_log_details`
token	✅	string	API-токен аутентификации
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": [
{
"event": "example_event",
"details": "example_detail"
}
]
}

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

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

```

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": "GITHUB_CLIENT_ID",
"redirect_uri": "GITHUB_REDIRECT_URI"
},
"error_code": null
}

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

``` {}

```

auth/github_signin¶

Выполняет обмен кода авторизации на access token GitHub и связывает аккаунт с пользователем (SSO). Если токен уже привязан, перенаправляет на страницу 'уже использовано', если нет — выполняет привязку.

HTTP-метод: POST

Параметры:

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

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

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

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

{
"result": "OK",
"sso": "github",
"sso_hash": "abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567",
"error_code": null
}

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

``` { "result": "error", "message": "Authorized, but unable to exchange code for token" }

```

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

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

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

```

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": "RU",
"servers": [
101,
102
],
"permissions": [
"manage_products",
"show_invoices",
"edit_master_profile"
],
"token_expire": 1735689600,
"new": 1,
"customer_id": 789,
"email": "user@example.com",
"subaccount": null,
"client_ip": "192.168.1.1",
"timing": [
{
"auth_validate_token": 5
},
{
"auth_get_role": 2
}
]
}

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

{
"code": -2,
"message": "auth: invalid token #13",
"tt": {
"error": "hash without tags found. Stop."
}
}

auth/login¶

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

HTTP-метод: POST

Параметры:

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

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

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

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

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

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

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

```

auth/logout¶

Очищает текущий токен доступа (access token)

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¶

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

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `session_reset`
token	✅	string	Токен авторизации (используется для получения hash)
user_email	✅	string	Email пользователя для сброса сессий
reset_token	✅	string	Специальный токен сброса (hash от token + reset_token)
confirm	✅	int	Подтверждение действия (должен быть равен 1)

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

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

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

{
"result": "OK"
}

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

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

```

auth/set_tag¶

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

HTTP-метод: POST|GET

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `set_tag`
tag	✅	string	Имя тега (максимум 32 символа). Для клиентов разрешен только 'auto_credit'.
set	✅	boolean	Установить значение (1) или удалить тег (0/null).
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 created/removed",
"action": "set/unset/absence",
"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_link"
}

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

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

```

auth/vk_init¶

Инициирует процесс авторизации через VK, генерируя временные параметры (code_challenge, state) и сохраняя их для последующей проверки при выполнении входа.

HTTP-метод: POST

Параметры:

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

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

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

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

{
"result": "OK",
"data": {
"client_id": "VK_CLIENT_ID_VALUE",
"redirect_uri": "VK_REDIRECT_URI",
"code_challenge": "base64url_encoded_hash",
"device_id": "random_24_chars_string",
"state": "random_30_chars_with_id"
}
}

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

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

```

auth/vk_signin¶

Выполняет авторизацию пользователя через OAuth2 протокол VK. Обменивает код на токен и связывает аккаунт с пользователем.

HTTP-метод: GET

Параметры:

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

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

curl -s "https://invapi.hostkey.ru/auth?action=vk_signin&state=VALUE&code=VALUE" -X GET

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

{
"result": "OK",
"sso": "vk",
"sso_hash": "string"
}

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

``` { "code": -1, "message": "Invalid host header" }

```

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

```