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

Используйте ключ API для вашего собственного бэкенда или автоматизации. Используйте OAuth, когда ваше приложение просит других пользователей Make Agent Fast предоставить доступ. Оба типа учётных данных вызывают те же ресурсы /api/v1 и подчиняются тем же областям, правам тарифа, изоляции арендаторов и лимитам частоты.

Ключи API#

Активный платный тариф требуется для создания и использования публичного ключа API.

1. Откройте Панель → Настройки → Разработчик.
2. Введите имя, идентифицирующее сервис и окружение, например Production lead export.
3. Выберите минимальные области, нужные сервису.
4. Выберите срок: 30 дней, 90 дней, один год или никогда.
5. Создайте ключ и немедленно скопируйте значение maf_live_....

Make Agent Fast хранит хеш SHA-256 вместо восстанавливаемого открытого текста. Панель позже показывает безопасный префикс, области, срок, время последнего использования и состояние отзыва.

Authorization: Bearer maf_live_...

Отправляйте заголовок из серверного кода:

curl --fail-with-body https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

Отсутствующие учётные данные возвращают 401 authentication_required. Недействительные, истёкшие или отозванные ключи возвращают 401 invalid_api_key. Ключ, чей аккаунт больше не имеет активного платного тарифа, возвращает 403 subscription_required.

Ротируйте или отзовите ключ#

Создайте замену перед отзывом старого ключа. Разверните замену, сделайте реальный запрос, проверьте его x-request-id, затем нажмите Отозвать на старом ключе. Отзыв мгновенен и не может быть отменён.

Области и срок нельзя расширить на существующем ключе. Создайте замену, чтобы изменение разрешений было явным.

OAuth-приложения#

OAuth — для ПО, подключающего аккаунты, принадлежащие другим пользователям Make Agent Fast. Он использует Authorization Code с PKCE (S256) и не выдаёт и не требует секрет клиента. ID клиента публичен; коды авторизации, токены доступа, токены обновления и верификатор PKCE чувствительны.

1. Зарегистрируйте приложение#

Откройте Панель → Настройки → Разработчик → OAuth-приложения. Добавьте:

• Имя приложения от 2 до 100 символов.
• От 1 до 10 точных URL перенаправления.
• Максимальные области, которые ваше приложение может запрашивать.

Продакшен URL перенаправления должны использовать HTTPS и не могут содержать учётные данные или фрагменты. Полный URI должен совпадать с зарегистрированным значением во время авторизации и обмена токенов. Недавно отправленные приложения имеют статус pending; авторизация работает только после того, как приложение проверено и помечено approved.

Владелец платформы проверяет ожидающие ID клиентов аудируемым процессом oauth:review. Сохраните ID клиента, показанный после отправки; его статус виден на странице Разработчика, и отклонённые приложения включают решение проверки перед возможностью повторной отправки.

2. Сгенерируйте значения PKCE#

Генерируйте новый верификатор для каждой попытки авторизации и держите его в той же защищённой короткоживущей сессии, что и state.

import { createHash, randomBytes } from "node:crypto";

const verifier = randomBytes(48).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const state = randomBytes(24).toString("base64url");

Верификатор должен содержать 43–128 URL-безопасных символов PKCE. Принимается только code_challenge_method=S256.

3. Перенаправьте пользователя для согласия#

https://makeagent.fast/oauth/authorize
  ?client_id=maf_app_...
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &response_type=code
  &scope=sites%3Aread%20leads%3Aread
  &state=RANDOM_STATE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

Пользователь входит, проверяет запрошенные области и разрешает или отказывает в доступе. При успехе Make Agent Fast перенаправляет на точный зарегистрированный URI с code и исходным state. При отказе отправляет error=access_denied и исходный state, когда он был предоставлен.

Отклоняйте обратный вызов, если state не совпадает точно со значением, сохранённым для этой браузерной сессии.

4. Обменяйте код авторизации#

Код авторизации истекает через 10 минут и может быть использован только один раз.

curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=https://app.example.com/oauth/callback" \
  --data-urlencode "code_verifier=$PKCE_VERIFIER"

{
  "access_token": "maf_live_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "maf_refresh_...",
  "scope": "sites:read leads:read"
}

Токен доступа длится один час. Токен обновления длится до 90 дней, если он не ротирован или отозван раньше.

5. Ротируйте токен обновления#

Каждое успешное обновление отзывает и отправленный токен обновления, и его предыдущий токен доступа, затем возвращает новую пару. Сохраняйте новую пару атомарно перед отбрасыванием состояния предыдущего ответа.

curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

Повторное использование кода авторизации или ротированного токена обновления возвращает invalid_grant. Конечная точка токенов OAuth возвращает ответы в стиле OAuth { "error", "error_description" } вместо оболочки ошибок публичного API и разрешает 30 запросов токенов на клиента и вызывающего в минуту.

Никогда не аутентифицируйте запросы управления в браузерном коде#

Не помещайте секретный ключ API, токен доступа или токен обновления в клиентские компоненты React, статический JavaScript, мобильный веб, Webflow, Framer, Wix или Shopify Liquid. Используйте ваш аутентифицированный бэкенд. Публичное встраивание сайта использует несекретный slug сайта и разрешённый список origin, а не учётные данные управления API.

См. Учётные данные и токены, Области и ошибки и Быстрый старт API.