Перейти к основному содержимому

Аутентификация для агентов

Агенты должны аутентифицироваться в FastNear так же, как это делают продовые бэкенды. Не переносите браузерно-демонстрационный режим из UI документации в агента, воркера или среду автоматизации.

Один API-ключ FastNear работает во всех RPC и API-эндпоинтах. Многие публичные чтения работают и без ключа. Для агента важнее не само наличие аутентификации, а где живёт учётная запись, как она прикрепляется к запросам и как не допустить её утечки в промпты, логи или состояние браузера.

Если нужно только правило​

  • Храните ключ в переменной окружения или менеджере секретов.
  • Внедряйте его со стороны сервера или из среды выполнения воркера.
  • Предпочитайте заголовок Authorization: Bearer ....
  • Одинаковые правила ключа и способа передачи действуют и для обычных, и для архивных RPC-хостов.
  • Никогда не просите пользователя вставлять ключ FastNear в чат, промпт или агента, работающего только в браузере.

Рекомендуемые шаблоны среды выполнения​

Используйте один из этих шаблонов:

  • Серверный воркер или автоматизация: загружайте ключ из переменных окружения или менеджера секретов и прикрепляйте его к исходящим запросам к FastNear напрямую.
  • Тонкий бэкенд-прокси: если пользовательское приложение работает в браузере, сначала отправляйте запрос на свой бэкенд, и пусть бэкенд подставляет учётные данные FastNear.
  • Мульти-тенантный сервис: храните ключи по тенантам в полноценном хранилище секретов и заставьте агента выбирать правильный ключ по контексту тенанта или проекта.

Избегайте архитектур «агент только в браузере», где ключ FastNear приходится держать в клиентском хранилище.

Выбор способа передачи учётных данных​

СпособИспользуйте, когда...Заметки
Authorization: Bearer ${API_KEY}HTTP-клиентом или бэкендом управляете выЛучшее значение по умолчанию для агентов. Меньше шансов утечь в логи URL, аналитику или скопированные ссылки.
?apiKey=${API_KEY}используется простой curl или система, которой сложно выставлять заголовкиТоже допустимо, но URL обычно дальше путешествуют через логи и инструменты. Применяйте осознанно.

Если есть выбор — используйте заголовочную форму.

Минимальный безопасный поток​

  1. Читайте ключ из переменной окружения или менеджера секретов во время выполнения.
  2. Прикрепляйте его к запросу как заголовок или URL-параметр.
  3. Чистите промпты, трассировки и логи, чтобы сырой ключ не попадал в транскрипты.
  4. Ротируйте ключ, если он появился в промпте, отладочной трассировке, браузерном хранилище или скопированном URL.

Пример:

const apiKey = process.env.FASTNEAR_API_KEY;

const response = await fetch('https://rpc.mainnet.fastnear.com', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'block',
    params: {finality: 'final'},
  }),
});

Когда аутентификации не хватает​

Многие публичные эндпоинты FastNear по-прежнему доступны на чтение без ключа. Если агент может ответить на вопрос пользователя через публичный трафик — делайте так.

Когда ключ нужен для повышенных лимитов, платного доступа или аутентифицированного трафика:

  • подскажите пользователю создать или забрать ключ на dashboard.fastnear.com
  • попросите настроить его в переменной окружения, менеджере секретов или конфигурации бэкенда
  • не просите вставлять сырой ключ в чат, чтобы агент «носил» его с собой

Если агент не может получить настроенный секрет — пусть честно скажет это и остановится, а не импровизирует небезопасное хранение.

Так делать не надо​

  • Не вынимайте ключ из браузерного localStorage и не считайте его учётной записью агента.
  • Не зашивайте ключи в агент-приложения, доставляемые в браузер.
  • Не храните ключи в промптах, ячейках ноутбуков или в виде открытого текста в конфигах, закоммиченных в систему контроля версий.
  • Не предпочитайте ?apiKey= только за краткость, если инфраструктура агрессивно логирует полные URL.

Что агенту стоит сказать пользователю​

Когда аутентификация уместна, полезный ответ агента обычно содержит:

  • можно ли выполнить текущий запрос без аутентификации
  • нужно ли пользователю далее настроить API-ключ FastNear
  • где этому ключу жить — обычно в переменной окружения, менеджере секретов или бэкенд-прокси
  • какой способ передачи использует агент — обычно Authorization: Bearer ...

Связанные руководства​