Аутентификация

Обновлено: 2026-06-25 13:29 MSK

Hostme API использует OAuth2 со схемой Resource Owner Password Credentials (password flow). Токен получаете по логину/паролю сервисной учётной записи и прикладываете его к каждому запросу в заголовке Authorization: Bearer <token>.

Шаг 1. Получение токена

Токен выдаётся по POST /Token в формате application/x-www-form-urlencoded:

curl -X POST https://api.hostmeapp.com/Token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "username=YOUR_USERNAME" \
  -d "password=YOUR_PASSWORD"

client_id и scope партнёрам указывать не нужно — достаточно grant_type, username, password. (Внутренняя админ-панель Hostme дополнительно шлёт client_id=panel, но для партнёрских интеграций это не требуется.)

Ответ:

{
  "access_token": "eyJhbGciOiJ...",
  "token_type": "bearer",
  "expires_in": 86399
}

Поле	Описание
`access_token`	Токен доступа. Прикладывается к каждому запросу к API.
`token_type`	Тип токена — `bearer`.
`expires_in`	Время жизни токена в секундах.

refresh_token в ответе POST /Token не возвращается — по истечении expires_in получите новый токен повторным запросом с логином/паролем.

Endpoint и окружения

Окружение	Token endpoint
Production	`https://api.hostmeapp.com/Token`
QA / Test	`https://api-qa.hostmeapp.com/Token`

Про swagger. В спецификации OAuth2 объявлен с tokenUrl: https://service.hostmeapp.com/token и scope All — это официальный сервер авторизации. На практике токен принимается и на базовом домене API ({API_BASE}/Token) — именно так логинится прод-панель, и этот путь рекомендуется для партнёрских интеграций. scope отправлять не обязательно.

Шаг 2. Использование токена

Прикладывайте access_token к каждому запросу:

curl https://api.hostmeapp.com/api/core/admin/account/me \
  -H "Authorization: Bearer eyJhbGciOiJ..."

Без действительного токена API вернёт 401 Unauthorized.

Шаг 3. Какой ресторан доступен — `GET /api/core/admin/account/me`

После получения токена узнайте, к каким ресторанам у вас есть доступ, и их restaurantId:

curl https://api.hostmeapp.com/api/core/admin/account/me \
  -H "Authorization: Bearer <token>"

Ответ — UserInfoContract. Ключевые поля:

Поле	Тип	Описание
`id`	string	Идентификатор пользователя/учётной записи
`email`	string	Email
`fullName`	string	Имя
`partnerId`	string	Идентификатор партнёра (если учётка партнёрская)
`roles[]`	array	Роли по ресторанам: `restaurantId`, `restaurantName`, `name`, `type`
`restaurants[]`	array	Доступные рестораны (см. ниже)

Элемент restaurants[] (RestaurantSummaryContract):

Поле	Тип	Описание
`id`	integer	`restaurantId` — используйте в путях `/restaurants/{restaurantId}/...`
`name`	string	Название
`address`, `city`, `country`, `countryShort`	string	Адрес
`timeZone`	string	Часовой пояс ресторана
`isVerified`	boolean	Верифицирован
`isSuspended`	boolean	Приостановлен
`isOnline`	boolean	Онлайн-приём броней включён
`role`	string	Ваша роль в ресторане

Типы токенов и поведение API

Поведение некоторых эндпоинтов зависит от типа токена, под которым выполнен запрос:

Тип токена	Кто это	Как создаются записи
Hostme	Хост/менеджер в админ-панели	От имени текущего пользователя
Partner	Партнёрская учётная запись	От имени текущего пользователя (хоста/менеджера)
Vendor	Внешнее приложение (POS, CRM)	От имени внешнего приложения; автоматически проставляется `VendorAppId`

Пример: при создании брони (POST .../reservations) под токеном Vendor бронь создаётся от имени внешнего приложения, а при выборке списка для scope App автоматически подставляется VendorAppId и требуется обязательный диапазон дат (не более 60 дней). Подробнее — в разделах Бронирования и Партнёрские брони.

Партнёрский токен — `POST /api/core/admin/account/partners/token`

Для партнёрских сценариев платформа поддерживает выдачу партнёрского токена через POST /api/core/admin/account/partners/token (тело — PartnerTokenRequest). Конкретная схема запроса согласуется индивидуально при подключении партнёра.

Точный формат тела PartnerTokenRequest и условия выдачи партнёрского токена предоставляет команда Hostme при онбординге партнёра — см. Регистрация приложения.

Обработка ошибок аутентификации

Код	Причина	Что делать
`401`	Токен отсутствует, истёк или недействителен	Получить новый токен; проверить заголовок `Authorization`
`403`	Нет прав на ресторан/действие	Проверить доступ учётной записи к `restaurantId`

Подробнее об ошибках — в разделе Ошибки и коды ответов.