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

Каждый запрос аутентифицируется API-ключом. Передавайте его как Bearer-токен:

Authorization: Bearer gsk_live_xxx

Если Bearer-токен неудобен в вашем стеке, принимается и заголовок x-api-key: gsk_live_xxx. Без ключа любой запрос получает 401 с title: invalid_key.

Формат ключа

gsk_live_<id>_<секрет> или gsk_test_<id>_<секрет>. Ключ gsk_live выполняет реальную работу, она оплачивается. Ключ gsk_test работает в песочнице: инструменты имитируются и ничего не списывается, а объекты, лиды и другие реальные данные им изменить нельзя. Тип ключа выбирается при создании.

Секрет показывается один раз при создании. GREM хранит только его хеш, поэтому потерянный ключ восстановить нельзя - создайте новый, а старый отзовите.

Управление ключами

В кабинете API → Ключи:

• Создать ключ с меткой. В расширенных настройках можно выбрать области доступа и срок действия в днях. Без выбора ключ получает все области.
• Ротировать - выпустить новый секрет; старый работает еще 24 часа, чтобы вы успели заменить его в интеграции.
• Отозвать - ключ перестает работать сразу и навсегда.

Статус ключа виден в списке: active - работает; suspended - доступ к API приостановлен администратором (обратимо, ключ не уничтожен); revoked - отозван. Ключ со сроком действия после его окончания перестает приниматься (401).

Ключи агентства

Владелец или менеджер агентства может выпустить ключ от имени агентства: переключите в списке ключей область «агентство». Такой ключ:

• видит объекты и лиды агентства, а не личные;
• может брать лиды из общего пула агентства и возвращать их (Лиды);
• может переносить объекты в агентство и назначать ответственного (Объекты).

Ключ можно привязать к конкретному агенту - тогда он действует от имени этого агента с его правами.

Области доступа

Каждый ключ несет набор областей. Вызов без нужной области возвращает 403 с title: forbidden_scope. Какая область нужна операции, указано в описании каждой операции в /openapi.json (поле x-required-scope).

Без какой-либо области доступны GET /ping, GET /me, GET /dictionaries, GET /objects, GET /voices, GET /tools/status и GET /works.

Что это за ключ

curl https://developers.grem.capital/api/v1/me \
  -H "Authorization: Bearer gsk_live_xxx"

GET /me возвращает идентификатор и префикс ключа, кому он принадлежит (subjectType: user или agency, subjectId, для ключа агента - agencyMemberId), выданные области, лимиты запросов, действующие именно для этого ключа (rateLimit.rpm в минуту и rateLimit.rpd в сутки), и срок действия. Секрет не возвращается никогда. Запрос бесплатный.

Безопасность

• Храните ключи в серверных переменных окружения или менеджере секретов.
• Заводите отдельный ключ под каждую интеграцию и давайте ему только нужные области - отзыв одного не заденет другие.
• Ротируйте ключи по расписанию.
• Запросы принимаются только по HTTPS.

Связанные статьи

• Ошибки - 401 и 403 подробно.
• Лимиты и оплата - что означают rpm и rpd.