Приложения OAuth

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

OAuth работает отдельно от публичных ключей API. Используйте OAuth, когда вам нужно действовать от имени вошедшего пользователя. Используйте ключи API для чтения публичных данных платформы на стороне сервера.

Создание приложения

Включите Режим разработчика и откройте Консоль разработчика.
Перейдите в раздел OAuth Apps и нажмите Create App.
Заполните название приложения, описание, иконку, веб-сайт и юридические ссылки.
На странице OAuth укажите redirect URIs (по одному в строке) и выберите scopes.
Сохраните изменения. Скопируйте client secret, когда он отобразится. Позже его нельзя будет восстановить.

Правила для Redirect URI

Точное совпадение требуется во время авторизации и получения токена (включая путь, порт и завершающий слэш).
https:// публичные хосты разрешены.
http:// разрешен только для хостов локальной разработки: localhost, *.localhost, 127.x.x.x, диапазонов частных локальных сетей (LAN) (10/8, 172.16/12, 192.168/16) и host.docker.internal.
Пользовательские схемы приложений разрешены для нативных клиентов (например, myapp://callback).
Фрагменты (#...) и встроенные учетные данные (user:pass@) отклоняются.

Типы приложений

Тип	Секретный ключ клиента	Типичное использование
confidential (по умолчанию)	Требуется на эндпоинте токена	Серверные веб-приложения и бэкенды
public	Не используется	Мобильные приложения и SPA, использующие PKCE

Публичные клиенты проходят аутентификацию на эндпоинте токена с опущенным параметром client_secret_post. Конфиденциальные клиенты должны отправлять client_secret.

Эндпоинты OAuth

Документ обнаружения (OAuth 2.0 Метаданные сервера авторизации):

GET https://trucklinemp.com/.well-known/oauth-authorization-server

Эндпоинт	URL
Авторизация	`https://trucklinemp.com/oauth/authorize`
Токен	`https://trucklinemp.com/api/oauth/token`
Отзыв	`https://trucklinemp.com/api/oauth/revoke`
Данные пользователя	`https://trucklinemp.com/api/oauth/userinfo`

Поддерживаемый тип ответа: code (авторизация с использованием кода).

Поддерживаемые типы разрешений: authorization_code, refresh_token.

Поддерживаемый метод PKCE: S256.

Области доступа

Область доступа	Доступ
`profile`	Имя пользователя, аватар и публичный профиль (обязательно)
`vtc:read`	Членство в VTC, роли и данные VTC
`events:read`	Зарезервировано для будущих полей информации о пользователе (пока не возвращается)
`bans:read`	Зарезервировано для будущих полей информации о пользователе (пока не возвращается)

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

events:read и bans:read доступны для запроса уже сегодня, но пока не добавляют поля в информацию о пользователе. Вместо этого для получения общедоступных данных о блокировках используйте конечные точки Public API, предназначенные для банов.

Поток авторизации

1. Перенаправление пользователя для авторизации

Сгенерируйте URL-адрес (или используйте ссылку install link на странице обзора вашего приложения):

https://trucklinemp.com/oauth/authorize
  ?client_id=tlmp_client_...
  &response_type=code
  &redirect_uri=https://your-app.com/callback
  &scope=profile vtc:read
  &state=RANDOM_CSRF_TOKEN

Если ваше приложение требует PKCE, также включите:

&code_challenge=CHALLENGE
&code_challenge_method=S256

Сгенерируйте challenge из code_verifier, используя SHA-256 и кодировку base64url.

2. Согласие пользователя

Пользователь выполняет вход (если необходимо) и одобряет запрошенные области доступа. TrucklineMP перенаправляет его обратно на ваш redirect_uri с параметрами code и state.

Убедитесь, что state совпадает с тем, который вы отправили, для предотвращения CSRF-атак.

3. Обмен кода на токены

curl -X POST "https://trucklinemp.com/api/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=tlmp_client_..." \
  -d "client_secret=tlmp_secret_..." \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://your-app.com/callback" \
  -d "code_verifier=VERIFIER_IF_PKCE"

Ответ включает access_token (tlmp_...) и, опционально, refresh_token (tlmpr_...).

4. Запрос данных пользователя

curl -H "Authorization: Bearer tlmp_ACCESS_TOKEN" \
  "https://trucklinemp.com/api/oauth/userinfo"

Ответ Userinfo

Поля зависят от областей доступа, предоставленных токену доступа. Субъект включается всегда.

Возвращается всегда

Поле	Тип	Описание
`sub`	string	ID пользователя TrucklineMP
`web_id`	string	Публичный WebID

С областью доступа `profile`

Поле	Тип	Описание
`name`	string	Отображаемое имя
`picture`	string	URL-адрес аватара
`handle`	string	Публичный `@handle` (может быть null)
`steam_id`	string \| null	Привязанный SteamID64

С областью доступа `vtc:read`

Поле	Тип	Описание
`vtc_memberships`	array	Объекты с `vtcId`, `vtcName`, `role`, `isOwner`, `joinedAt`

Пример

{
  "sub": "user_abc123",
  "web_id": "10042",
  "name": "Driver Name",
  "picture": "https://cdn.example/avatar.webp",
  "handle": "drivername",
  "vtc_memberships": [
    {
      "vtcId": 7,
      "vtcName": "Example Logistics",
      "role": "Driver",
      "isOwner": false,
      "joinedAt": "2026-01-15T10:00:00.000Z"
    }
  ]
}

Недействительные или просроченные токены возвращают HTTP 401 с { "error": "invalid_token" }.

PKCE

PKCE защищает публичных клиентов, которые не могут хранить секретный ключ клиента. Включите Require PKCE в настройках безопасности вашего приложения, чтобы отклонять запросы на авторизацию без обоснованного возражения.

Когда требуется PKCE:

Сгенерируйте code_verifier (случайная строка в формате base64url).
Вычислите code_challenge = BASE64URL(SHA256(code_verifier)).
Отправьте code_challenge и code_challenge_method=S256 в запросе на авторизацию.
Отправьте code_verifier в запросе токена.

Режим тестирования и тестовые пользователи

Новые сторонние приложения изначально создаются неопубликованными. Пока приложение не опубликовано:

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

Добавляйте тестовых пользователей на вкладке General в настройках вашего приложения. Ищите пользователей TrucklineMP по имени или никнейму. Список тестовых пользователей также может включать адреса электронной почты, которые соответствуют авторизующемуся аккаунту.

Это позволяет вам заниматься разработкой и тестированием (QA), не открывая доступ к приложению всем пользователям TrucklineMP.

Публикация

Когда ваше приложение готово для публичного использования:

Пройдите верификацию домена для вашего веб-сайта и URI перенаправления (требуется для конфиденциальных конфигураций).
Откройте страницу Publishing в настройках приложения.
Нажмите Verify / Publish App, чтобы отправить его на проверку администрации, если это требуется.
После одобрения используйте Publish App, чтобы сделать приложение доступным для всех пользователей.

Опубликованные приложения могут быть снова сняты с публикации на этой же странице. Снятие с публикации возвращает приложению ограничения режима тестирования.

Администрация может отклонить заявку приложения, оставив заметки с объяснением того, что нужно исправить. Учтите замечания и отправьте заявку повторно.

Форматы токенов

Элемент	Префикс / формат
Client ID	`tlmp_client_...`
Client secret	`tlmp_secret_...`
Access token	`tlmp_...`
Refresh token	`tlmpr_...`

Обновите client secret на странице безопасности, если он был скомпрометирован. Существующие токены могут быть аннулированы в зависимости от ваших настроек ротации.

Контрольный список безопасности

Используйте HTTPS для redirect URIs на рабочей версии.
Всегда проверяйте параметр state.
Используйте PKCE для публичных клиентов и браузерных приложений.
Храните client secrets и refresh tokens только на стороне сервера.
Запрашивайте только минимально необходимые области доступа.