Кожен запит автентифікується 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).
| Область | Що відкриває |
|---|---|
ping | перевірку ключа (сам GET /ping працює і без неї) |
tools:valuation | експрес-оцінку і повний звіт про вартість |
tools:rent | оцінку оренди |
tools:review | перевірку чужого звіту про оцінку |
tools:contentgen | пакет контенту для оголошення |
tools:text | тексти оголошення |
tools:video | відео з фото, перелік музики і фінальних фраз |
tools:avatar | відео з аватаром і перелік аватарів |
tools:photo | покращення фото |
tools:floorplan | очищення планування |
tools:sitegen | сайт об'єкта |
tools:pdf | PDF-презентацію |
tools:flyer | персональний флаєр брокера |
tools:draft | чернетку оголошення з документів або сайту |
tools:chat | чат з AI-асистентом |
tools:artifacts | завантаження готових файлів |
objects:write | створення, зміну і видалення ваших об'єктів |
leads:read | читання лідів і лідів Swipe Match |
leads:write | створення і зміну лідів, події Swipe Match |
media:write | завантаження зображень |
webhooks | керування підписками на події |
Без жодної області доступні 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 за добу), і термін дії. Секрет не повертається ніколи. Запит безкоштовний.
Безпека
Не розміщуйте ключ у коді браузера, мобільного застосунку, публічному репозиторії чи URL. Будь-хто з ключем витрачає кошти вашого акаунта. Якщо ключ витік, відкличте його негайно.
- Зберігайте ключі в серверних змінних середовища або менеджері секретів.
- Заводьте окремий ключ під кожну інтеграцію і давайте йому лише потрібні області - відкликання одного не зачепить інші.
- Ротуйте ключі за розкладом.
- Запити приймаються тільки по HTTPS.
Пов'язані статті
- Помилки -
401і403докладно. - Ліміти і оплата - що означають
rpmіrpd.