Ключи API и их права
У каждого ключа Планёрки свой набор прав. Ключ с ограниченными правами вписывают прямо в страницу сайта, и это не утечка. Ключ, которому можно всё, на страницу класть нельзя.
Что такое ключ API
Ключ — это способ обратиться к Планёрке от вашего имени, без логина и пароля. Кто предъявил ключ, тот для API и есть владелец кабинета: своего пользователя ключ приводит с собой, поэтому нигде не нужно отдельно указывать, чьё это расписание.
Выглядит он так: cal_ и 64 символа следом. Программа передаёт его двумя заголовками:
Authorization: Bearer cal_7f3a…
cal-api-version: 2024-08-13Ключи заводятся в кабинете: «Разработчикам» → «Ключи API». Раздел открыт на любом платном тарифе.
Ключ показывается один раз
В базе Планёрки лежит только его отпечаток, самого ключа там нет — восстановить его мы не сможем даже по вашей просьбе. Не сохранили — отзовите и создайте новый, это минутное дело.
Права выбираются один раз
При создании ключа вы отмечаете, что ему можно. Всего таких разрешений шесть — их называют скоупами:
Отмечать их по одному не нужно, в окне создания есть готовые наборы:
Права потом не поменять
Набор фиксируется в момент создания. Понадобилось больше или меньше — отзовите ключ и заведите новый. А вот список разрешённых сайтов у ключа правится в любой момент.
Начинайте с минимальных прав
Правило простое: заводите «Публичный для сайта» и расширяйте права, только когда упрётесь в их нехватку.
Ключ с этим набором можно публиковать. Вписать прямо в html‑файл, в блок «HTML‑код» конструктора, в код приложения — куда угодно, где его увидит посетитель. Так и задумано.
Посмотрите, что по нему делают. Узнают, какие у вас есть типы встреч. Узнают, когда вы свободны. Записываются. Ровно это же делает любой человек, открывший вашу страницу записи. Списка ваших клиентов по такому ключу не видно, отменить чужую встречу нельзя, до настроек кабинета не добраться.
Готовый пример первой схемы — «Страница записи с котом»: ключ вписан прямо в файл страницы, и менять в нём нужно ровно одну строку.
Разрешённые сайты
У публичного ключа есть вторая половина защиты — список адресов, с которых он работает. Планёрка смотрит, откуда пришёл запрос, и с чужого адреса отвечает отказом. Поле появляется, как только у ключа есть право создавать записи.
Список правится в любой момент, отзывать ключ для этого не нужно. Правка доезжает секунд за сорок пять — столько живёт кэш.
Если страница пишет «не удалось загрузить»
Почти всегда адрес не в списке. API отвечает 403 Origin not allowed, но в консоли браузера (F12) видно только Failed to fetch: ответ, который браузер сам заблокировал, он же и прячет. Проверяйте адрес страницы в разрешённых — целиком и посимвольно.
Когда всё-таки нужен полный ключ
Ключа с ограниченными правами не хватит, если задача трогает уже созданные записи:
- выгрузить записи в таблицу или CRM;
- отменить или перенести встречу из бота;
- собрать сводку за неделю: сколько пришло, сколько отменилось;
- построить свой кабинет поверх Планёрки.
В каждом случае ключ видит контакты ваших клиентов — имена, почту, телефоны — и может отменить любую встречу. Это уже пароль от кабинета. На страницу его класть нельзя: исходный код страницы открывается правой кнопкой мыши.
Такому ключу нужно место, где он лежит закрыто, а наружу выдаётся только результат. Как собрать такое место бесплатно, без сервера и без карты, — в рецепте «Где хранить ключ, если вы не программист». Поверх той же прослойки работает и форма записи на Тильде.
Несколько правил
- На каждую задачу — свой ключ со своей меткой. Тогда отзыв одного не ломает остальные.
- Права берите по минимуму. Нужно только показать расписание — хватит «Только чтение», создавать записи такому ключу незачем.
- Ключи, созданные до появления прав, работают как «Полный доступ». Если у вас такой — заведите новый с нужным набором, а старый отзовите.
- Отдали ключ подрядчику — после сдачи работы отзовите его и создайте новый.
