Foxguide API

Быстрый старт

Как получить API-токен, выполнить первый аутентифицированный запрос и прочитать ответ.

Три шага: выпустить токен, вызвать эндпоинт с ним, прочитать конверт ответа.

1. Выпустите токен

Токены создаются в интерфейсе платформы, под сессией пользователя, а не через этот API. Откройте экран API-токенов своей команды, выберите области доступа (scopes), которые нужны интеграции, и создайте токен.

Токеном нельзя выпустить токен. Управление токенами живёт по пути /v1/api-tokens, и этот путь намеренно не входит в публичную поверхность: API-токен, способный выпускать API-токены, мог бы расширить собственные области доступа — а это ровно та привилегия, ради удержания которой существует модель scopes.

Токен выглядит так:

fgd_live_a1b2c3d4e5f6789012345678abcdef01234567890abcdef1234567890abcdef

За префиксом fgd_live_ идут 64 шестнадцатеричных символа криптографически случайного секрета.

Секрет показывается ровно один раз

При создании — и больше никогда. Платформа хранит только SHA-256-хеш, поэтому нет ни экрана, ни обращения в поддержку, ни запроса к базе, который позволил бы восстановить значение позже. Скопируйте его в своё хранилище секретов до закрытия диалога; если значение потеряно, выполните ротацию токена и возьмите новое.

Несколько ограничений, о которых стоит знать заранее:

ограничениезначение
токенов на команду50
лимит частоты по умолчанию60 запросов/минуту
максимальный лимит частоты600 запросов/минуту
максимальный срок действия365 дней с момента создания

2. Выполните запрос

Передавайте токен как bearer-учётные данные:

curl https://api.foxguide.io/v1/tables \
  -H 'Authorization: Bearer fgd_live_a1b2c3d4...'

Продакшн-хост — https://api.foxguide.io. Стейджинг-хост https://api.stage.foxguide.io обслуживает тот же контракт на данных стейджинга.

По умолчанию не выдаётся ничего. Токен достигает эндпоинта только тогда, когда его список областей доступа называет сущность этого эндпоинта и действие, которое эндпоинт выполняет — см. Аутентификация: там разобрана модель и тот отказ, который вы встретите при недостающей области доступа.

3. Прочитайте ответ

Одиночный ресурс приходит сам по себе либо обёрнутым в data. Коллекция всегда приходит конвертом с блоком pagination:

{
  "data": [ { "id": "tbl_...", "name": "Leads" } ],
  "pagination": { "limit": 20, "offset": 0, "hasMore": true, "total": 137 }
}

Ошибки плоские и всегда одной формы:

{ "error": "INSUFFICIENT_SCOPE", "message": "API token does not have scope table:write" }

Ветвитесь по HTTP-статусу и по полю error — никогда по наличию полезной нагрузки. Ошибки разбирают статусы и то, какие из них имеет смысл повторять; Постраничная выдача — обход коллекции.

Ротация без простоя

Когда токен нужно заменить, выполняйте ротацию, а не «удалить и создать заново». Ротация выпускает новый секрет и оставляет старый действительным ещё на 24 часа (льготный период), поэтому работающая интеграция может подхватить новое значение в своём темпе, а не падать между двумя вызовами.

Что дальше

← Вся документация