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

API Telegfy позволяет создавать ссылки, забирать отчёты и передавать расходы из своих систем. Все запросы идут на базовый адрес https://<api-host>/api/v1. Здесь и далее <api-host> — адрес API вашей установки. Проверка работоспособности — GET /health без префикса.

Два способа авторизации

Способ	Заголовок	Для чего
API-ключ	X-API-Key: la_…	Интеграции, скрипты, серверы. Права ограничены scopes.
Сессия	Authorization: Bearer <JWT>	Фронтенд и вход пользователя. Права — по роли в воркспейсе.

Если передан X-API-Key, но ключ неверный, на маршрутах, требующих авторизации, запрос падает с 401. Не смешивайте оба заголовка в одном запросе.

Создание ключа

Откройте API-ключи (/dashboard/api-keys) и нажмите «Создать API-ключ».

1. Название — до 100 символов. Нужно, чтобы через месяц понимать, где ключ используется.
2. Права доступа (scopes) — список ниже. По умолчанию выбраны links:read, links:write, analytics:read.
3. Истекает — необязательно. Ключ перестанет работать после этой даты.

Ключ показывается один раз

Сразу после создания появится окно с полным ключом. Повторно его показать нельзя. В списке остаётся только префикс вида la_xxxxxxxx. Если ключ потерян, отзовите его и создайте новый.

Ключ хранится в виде bcrypt-хэша. Отзыв — кнопка «Отозвать». Отозванный или истёкший ключ сразу перестаёт работать.

Как ключ работает внутри воркспейса

• Ключ действует в воркспейсе, где он создан.
• Права ключа — это права его владельца в этом воркспейсе: роль и ограничения участника (см. доступ байеров). Если владелец ключа удалён из воркспейса, деактивирован или ключ отозван, запрос получит 401.
• Ключ, созданный владельцем, видит всё, что видит владелец. Ключ, созданный наблюдателем, остаётся в режиме только чтения, как и его владелец.

Scopes

Scope	Что открывает	Включает
links:read	Чтение ссылок, коллекций, правил, симулятор	—
links:write	Создание, изменение, удаление ссылок, правил и коллекций	links:read
analytics:read	Аналитика по ссылкам, коллекциям и обзор аккаунта, воронка	—
reports:read	Отчёты, журналы кликов и конверсий, CSV-выгрузка, сохранённые отчёты (чтение)	—
offers:read	Офферы, лендинги, партнёрские сети (чтение)	—
offers:write	Создание, изменение, удаление офферов, лендингов и ПП	offers:read
costs:read	Список расходов	—
costs:write	Создание, массовая загрузка, изменение и удаление расходов	costs:read
conversions:read	Цели конверсий, журнал постбеков	—
conversions:write	Создание, изменение целей, импорт конверсий	conversions:read
postbacks:read	Источники трафика и их исходящие постбеки, CAPI-интеграции (чтение)	—
postbacks:write	Создание, изменение и удаление источников и CAPI-интеграций	postbacks:read
admin:read	Все *:read сразу	links, analytics, offers, costs, conversions, postbacks, reports
admin:write	Все scopes сразу	всё

Scope admin:* не требуется ни одним маршрутом напрямую, он работает только через включение.

Для маршрута нужны все scopes, которые на него требуются. Ключ с links:write и без links:read получит links:read автоматически, потому что write включает read.

Какие маршруты открывает каждый scope

Scope	Маршруты (префикс /api/v1)
links:read	GET /links/list, GET /links/:code/rules, POST /links/:code/simulate, GET /collections, GET /collections/:id
links:write	POST /links, PATCH /links/:code, DELETE /links/:code, POST/PATCH/DELETE /links/:code/rules[/:ruleId], POST/PATCH/DELETE /collections[/:id], POST /collections/:id/links, DELETE /collections/:id/links/:linkId
analytics:read	GET /links/:code/analytics/* (сводка, по времени, рефереры, устройства, гео, тепловая карта, языки, аномалии, A/B, экономика, экспорт), GET /analytics/overview/*, GET /links/:code/analytics/funnel, GET /collections/:id/analytics/*
reports:read	POST /analytics/report, POST /analytics/report/export, GET /analytics/clicks, GET /analytics/conversions, GET /analytics/reports, GET /analytics/reports/:id, GET /analytics/reports/:id/run
offers:read	GET /offers, GET /offers/stats, GET /offers/:id/stats, GET /offers/:id, GET /landings…, GET /affiliate-networks…
offers:write	POST/PATCH/DELETE /offers[/:id], POST/PATCH/DELETE для лендингов и партнёрских сетей
costs:read	GET /costs
costs:write	POST /costs, PUT /costs/bulk, PATCH /costs/:id, DELETE /costs/:id
conversions:read	GET /conversions/goals, GET /conversions/postback-logs
conversions:write	POST /conversions/goals, PATCH/DELETE /conversions/goals/:id, POST /conversions/import
postbacks:read	GET /traffic-sources…, GET /traffic-sources/:id/postbacks, GET /capi-integrations…
postbacks:write	POST/PATCH/DELETE /traffic-sources[/:id], POST/PATCH/DELETE /capi-integrations[/:id]

Маршруты без авторизации, доступные всем: GET /links/:code (редирект-информация), GET/POST /postback, POST /conversions/track, POST /track/pageview, публичные отчёты и дашборды по токену, /health.

Что ключом недоступно

Всё, что не перечислено выше, ключом не открывается. Ответ: 403 This route is not available to API keys. Сюда относятся: вход и пароли, пользователи, управление API-ключами, воркспейсы и участники, биллинг, свои домены, UTM-шаблоны, фильтры ботов, настройки приёма кликов, курсы валют, списки, алерты, вебхуки, защита постбеков, журнал аудита, дашборды (управление), ссылки в профиле, служебные маршруты.

Сохранять отчёты (POST /analytics/reports и изменение) ключом нельзя — только через сессию.

Ошибки

Все ошибки в одном формате:

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "API key is missing required scope(s): reports:read",
  "code": "API_KEY_SCOPE_INSUFFICIENT",
  "timestamp": "2026-10-13T09:15:00.000Z",
  "path": "/api/v1/analytics/report"
}

Код	Значит
401	Ключ неверный, отозван, истёк, владелец удалён из воркспейса или деактивирован.
403 API_KEY_SCOPE_INSUFFICIENT	Не хватает scope. Поле requiredScopes покажет, какие нужны.
403 This route is not available to API keys	Маршрут ключом не открывается.
402 UPGRADE_REQUIRED	Функция или лимит не входит в ваш тариф.
429	Превышен лимит запросов. Смотрите Retry-After.

Успешный ответ обёрнут в { "data": … }. Редиректы и 204 No Content без обёртки.

Лимиты запросов

Лимит — количество запросов в минуту на один эндпоинт, а не на весь API. Значения по тарифу владельца ключа:

Тариф	Запросов в минуту на эндпоинт
Анонимно (без ключа)	10
Free	30
Pro	120
Enterprise	600

• Счётчик общий для всех ключей одного владельца, потому что считается по пользователю.
• Ответ содержит заголовки X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. При 429 — Retry-After в секундах.
• Отдельные лимиты: POST /links анонимно — 10 в минуту. Постбеки GET/POST /postback — до 6000 в минуту с одного IP. POST /conversions/track — 600 в минуту. Вход — 5 попыток в минуту с IP.
• Редиректы и /health лимитом не ограничиваются.

Первый запрос

Создайте ключ со scope reports:read и выполните отчёт по ссылкам за неделю:

export TELEGFY_API="https://<api-host>/api/v1"
export TELEGFY_KEY="la_…"

curl -sS -X POST "$TELEGFY_API/analytics/report" \
  -H "X-API-Key: $TELEGFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2026-10-06T00:00:00Z",
    "to": "2026-10-12T23:59:59Z",
    "groupBy": ["link"],
    "metrics": ["clicks", "conversions", "revenue", "cost", "roi"],
    "orderBy": { "field": "roi", "direction": "desc" },
    "limit": 50
  }'

Ответ: data.rows — строки с dimensions и metrics, data.totals — итоги. Метрики и их формулы — в отчётах.

Список ссылок тем же ключом (scope links:read):

curl -sS "$TELEGFY_API/links/list" -H "X-API-Key: $TELEGFY_KEY"

Ключ наследует ограничения владельца

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

Справочник эндпоинтов

В справочнике API описаны все эндпоинты, доступные по API-ключу, а также публичные /postback и /track. Справочник собирается из кода бэкенда, поэтому совпадает с тем, что реально работает. Какой scope нужен каждому маршруту — в таблице выше.

Связанное

• Отчёты — поля и формулы того, что возвращает analytics/report.
• Расходы — ручной ввод расходов через API.
• Входящие постбеки — постбеки работают без ключа.
• Доступ байеров — ограничения, которые действуют и на ключ.