Начало работы

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

Каждый запрос передаёт секретный ключ аккаунта X, с которым он работает. Ключи создаются в приложении, их можно ограничить чтением, и они перестают работать в тот момент, когда вы их отзываете.

API-ключи

Ключ состоит из gl_live_ и 32 букв и цифр. Приложение показывает его первые 12 символов, например gl_live_AbCd, чтобы ключи было легко различать.
Каждый ключ принадлежит одному аккаунту X в Gemlead и видит только лидов, персоны, кампании и диалоги этого аккаунта.
Полный ключ показывается один раз, при создании. Gemlead хранит только его хеш, поэтому потерянный ключ показать снова нельзя. Создайте новый.
У аккаунта может быть до 20 активных ключей.

API входит в тарифы Business и Enterprise, включая пробный период. Если владелец аккаунта на тарифе Free или Starter, запросы получают ответ 403 с кодом plan_required. Ключи сохраняются и снова начинают работать, как только аккаунт переходит на Business или Enterprise.

Передача ключа

Передавайте ключ как bearer-токен в заголовке Authorization. Для инструментов, которые не умеют задавать bearer-токен, подойдёт и заголовок X-Api-Key.

Запрос без ключа получает ответ 401 с кодом api_key_missing, с неверным ключом api_key_invalid, а с отозванным api_key_revoked.

Терминал

# As a bearer token
curl https://gemlead.ai/api/v1/account \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

# Or in X-Api-Key, for tools that cannot set a bearer token
curl https://gemlead.ai/api/v1/account \
  -H "X-Api-Key: $GEMLEAD_API_KEY"

Права доступа

У ключа есть право read или права read и write. Давайте write только тем инструментам, которые меняют данные.

Право	Что разрешает
`read`	Все `GET`, а также `POST /v1/exports`, потому что экспорт только читает данные.
`write`	Все запросы, которые меняют данные, `POST`, `PATCH`, `PUT` и `DELETE`.

Ключ только с read при попытке изменить данные получает ответ 403 с кодом insufficient_scope.

Получение аккаунта

GET/v1/accountПраво readMCPget_account

Возвращает аккаунт X, которому принадлежит ключ. Хороший первый запрос, чтобы проверить ключ.

Возвращает

Объект аккаунта с plan, равным business или enterprise.

Ошибки

401api_key_invalid
Неверный ключ.
403plan_required
Владелец аккаунта на тарифе Free или Starter.

GET/v1/account

curl https://gemlead.ai/api/v1/account \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Ответ200

{
  "object": "account",
  "id": "a9PzK2vRtM",
  "username": "acme",
  "name": "Acme",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1180044592/acme_400x400.jpg",
  "plan": "business"
}

Защита ключей

Вызывайте API только со своего сервера, никогда из браузера, мобильного приложения или кода публичного репозитория.
Храните ключи в менеджере секретов или в переменной окружения, например GEMLEAD_API_KEY.
Выдавайте каждому инструменту отдельный ключ, чтобы отзывать один, не затрагивая остальные.
Чтобы сменить ключ, создайте новый, выкатите его в продакшен, а затем отзовите старый в приложении.

ИИ-ассистенты

Claude и ChatGPT подключаются к MCP-серверу через OAuth. Вы входите в Gemlead и выбираете аккаунт X, копировать ключ не нужно. Cursor и Claude Code могут использовать ключ, передавая его так же, как описано выше.