Yandex Metrika

CLI-токен

Описание

Общее описание функционала

CLI-токен — персональный токен для подключения CLI-клиента ForTunnels к аккаунту пользователя. Он позволяет один раз настроить клиент на рабочей машине и дальше запускать туннели командами вроде fortunnels http 8080 без ручной передачи токена в каждом запуске.

CLI-токен создаётся в дашборде аккаунта на платном тарифе (функция CLI-токен в каталоге), показывается пользователю один раз и сохраняется локально в конфигурационный файл CLI. На бесплатном тарифе управление CLI-токенами в интерфейсе недоступно, а API отклоняет запросы с понятным кодом ограничения тарифа. Пользователь может видеть список активных CLI-токенов и отзывать те, которые больше не нужны.

Как пользователь может использовать

  • Разработчик создаёт CLI-токен на своём ноутбуке и настраивает CLI один раз, чтобы быстро запускать HTTP-туннели к локальному приложению.
  • Инженер использует отдельные CLI-токены для разных рабочих машин, чтобы при потере доступа к одной машине отозвать только её токен.
  • Пользователь копирует готовую команду fortunnels config add-authtoken ... из дашборда и не редактирует YAML вручную.
  • Пользователь проверяет локальный файл конфигурации командой fortunnels config check, прежде чем запускать туннель.
  • Пользователь удаляет старый CLI-токен из дашборда, когда меняет устройство или больше не использует CLI на конкретной машине.
  • Пользователь на бесплатном тарифе видит, что создание CLI-токена недоступно, и может перейти к смене тарифа из подсказки в интерфейсе.
  • Пользователь на Pro или Enterprise создаёт и отзывает CLI-токены как обычно.
  • Команда поддержки или администратор может попросить пользователя отозвать CLI-токен, если есть подозрение, что он был скомпрометирован.
  • Пользователь хранит CLI-токен в стандартном для своей ОС месте: Linux, macOS и Windows используют разные пути, но CLI выбирает их автоматически.

Как это реализовано в сервисе

Пользователь создаёт CLI-токен в дашборде, сервис показывает секретное значение только в момент создания, а затем хранит у себя только безопасное представление токена. Когда CLI отправляет запрос на создание туннеля, сервис распознаёт персональный токен, связывает запрос с аккаунтом владельца и применяет обычные правила доступа, тарифов и блокировок.

Локальная команда конфигурации записывает CLI-токен в файл на машине пользователя. При запуске туннеля CLI читает этот файл, если токен не был передан более явным способом через флаг, файл секрета, stdin или переменную окружения.

Как использовать через CLI-клиент

После создания CLI-токена в дашборде сохраните его в локальной конфигурации клиента:

fortunnels config add-authtoken <ваш_токен>

Проверить, что файл конфигурации читается корректно:

fortunnels config check

Дальнейшие запуски туннелей (fortunnels http 8080, fortunnels tcp 22 и другие протоколы) подхватят токен автоматически; явная передача -token или переменной FORTUNNELS_TOKEN имеет более высокий приоритет. Подробнее — документация CLI-клиента.

Справочник API

Дашборд: управление токенами

Пользователь управляет CLI-токенами из дашборда. Эти маршруты требуют активной браузерной сессии. Для небезопасных методов используется защита CSRF, как и для других действий дашборда.

Получить список токенов

GET /api/me/authtokens

На бесплатном тарифе без возможности CLI-токен в плане: HTTP 403, JSON code: feature_disabled, feature_id: authtoken.

Успешный ответ:

{
  "authtokens": [
    {
      "id": 1,
      "name": "Laptop",
      "prefix": "ft_abc123",
      "created_at": "2026-05-31T21:00:00Z",
      "last_used_at": "2026-05-31T21:10:00Z",
      "expires_at": null
    }
  ]
}

Полное значение токена в списке не возвращается.

Создать токен

POST /api/me/authtokens

На бесплатном тарифе без возможности CLI-токен в плане: HTTP 403, JSON code: feature_disabled, feature_id: authtoken, текст authtoken requires a paid plan.

Тело запроса:

{
  "name": "Laptop",
  "expires_at": "2026-12-31T00:00:00Z"
}

Поля name и expires_at необязательны.

Успешный ответ:

{
  "id": 1,
  "name": "Laptop",
  "prefix": "ft_abc123",
  "authtoken": "ft_..."
}

Поле authtoken показывается только один раз — в ответе на создание.

Отозвать токен

DELETE /api/me/authtokens/{id}

Успешный ответ: 204 No Content.

CLI: локальная конфигурация

CLI поддерживает команды:

fortunnels config add-authtoken YOUR_FORTUNNELS_TOKEN
fortunnels config check

config add-authtoken записывает токен в конфигурационный файл. config check проверяет наличие файла, корректность YAML, версию схемы и наличие agent.authtoken. Команда не обращается к серверу.

Формат файла:

version: 3

agent:
  authtoken: YOUR_FORTUNNELS_TOKEN

Пути по умолчанию:

  • Linux: ~/.config/fortunnels/fortunnels.yml
  • macOS: ~/Library/Application Support/fortunnels/fortunnels.yml
  • Windows: %LOCALAPPDATA%\fortunnels\fortunnels.yml

Переменная FORTUNNELS_CONFIG задаёт пользовательский путь к конфигурационному файлу.

CLI: запуск туннеля

После настройки CLI использует CLI-токен из конфигурации при командах:

fortunnels http 8080

Более явные источники учётных данных имеют приоритет над конфигурационным файлом: флаг --token, затем --login с паролем (--pass, файл, stdin или FORTUNNELS_PASSWORD), затем --token-file, stdin и переменная FORTUNNELS_TOKEN. Сохранённый в fortunnels.yml CLI-токен используется только если выше ничего не задано.

Если одновременно указаны --login и токен в fortunnels.yml, клиент игнорирует файл и входит по логину и паролю; в stderr выводится предупреждение. Если используется только устаревший или недействительный токен из файла, клиент завершает работу с ошибкой (локально для просроченного JWT или после ответа сервера для недействительного ft_*) и подсказывает обновить или удалить agent.authtoken.

Ошибки

Ошибки дашборда

  • HTTP 401: пользователь не вошёл в аккаунт или сессия истекла. Нужно войти в дашборд заново.
  • HTTP 400: запрос на создание токена некорректен, например указан неверный формат expires_at. Нужно исправить данные и повторить действие.
  • HTTP 403: действие заблокировано политикой доступа, CSRF-проверкой или ограничением тарифа. При code: feature_disabled и feature_id: authtoken сообщение указывает, что CLI-токен недоступен на текущем плане (authtoken requires a paid plan); нужно сменить тариф или обратиться к администратору.
  • HTTP 404: пользователь пытается отозвать несуществующий токен или токен, который ему не принадлежит. Нужно обновить список токенов.
  • HTTP 409: достигнут лимит активных токенов. Нужно отозвать старый токен и создать новый.
  • HTTP 500: внутренняя ошибка сервиса. Нужно повторить позже или обратиться в поддержку.

Ошибки CLI-конфигурации

  • No configuration file at ...: файл конфигурации не найден. Нужно создать его вручную или выполнить fortunnels config add-authtoken <token>.
  • config version must be 3: версия схемы в YAML не поддерживается. Нужно указать version: 3.
  • agent.authtoken is required: в конфигурации нет токена. Нужно добавить agent.authtoken.
  • Ошибка парсинга YAML: файл имеет некорректный синтаксис. Нужно исправить отступы и структуру YAML.
  • LOCALAPPDATA is not set на Windows: CLI не смог определить стандартный путь. Нужно задать LOCALAPPDATA или FORTUNNELS_CONFIG.

Ошибки запуска туннеля с CLI-токеном

  • HTTP 401 при создании туннеля: токен неверный, отозван, истёк или не принят сервером. Нужно создать новый токен в дашборде и обновить локальную конфигурацию.
  • HTTP 403 при создании туннеля: аккаунт заблокирован или действие запрещено тарифом/политикой доступа. Нужно проверить статус аккаунта и ограничения тарифа.
  • Сообщение о недоступном сервере: CLI не смог подключиться к серверу ForTunnels. Нужно проверить сеть и DNS для fortunnels.ru.

Ограничения

Одноразовый показ токена

Полное значение CLI-токена показывается только сразу после создания. Если пользователь закрыл окно или не сохранил токен, нужно создать новый токен и отозвать старый.

Локальная проверка конфигурации

fortunnels config check проверяет только локальный файл: путь, YAML, версию схемы и наличие agent.authtoken. Команда не подтверждает, что токен действителен на сервере.

Ручная защита локального файла

CLI записывает конфигурационный файл с ограниченными правами, но пользователь отвечает за безопасность своей машины, резервных копий и синхронизаций домашней директории.

Лимит активных токенов

У аккаунта есть ограничение на количество активных токенов. Если лимит достигнут, нужно отозвать неиспользуемые токены.

Тарифный план

Функция CLI-токен доступна только когда она включена в активный тариф пользователя (по умолчанию — платные планы Pro и Enterprise). На Free дашборд не загружает список токенов и блокирует создание и отзыв; прямые запросы к API управления токенами возвращают отказ с кодом feature_disabled.

Приоритет источников токена

Если пользователь одновременно указал токен через флаг, переменную окружения и конфигурационный файл, CLI выберет более явный источник. Это может выглядеть так, будто конфигурационный файл игнорируется.

Отзыв не завершает уже запущенный процесс мгновенно

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