Аутентификация
Все запросы к API авторизуются по токену доступа (bearer-токен). Токен создаётся в настройках аккаунта Coverse и передаётся в каждом запросе.
Как получить токен
Настройки аккаунта → раздел «Автоматизация и API» → создайте токен и выберите права (scopes). Токен показывается один раз при создании — сразу сохраните его в надёжном месте.
Как передавать токен
В заголовке Authorization:
Authorization: Bearer ВАШ_ТОКЕН
curl "https://app.coverse.team/api/v1/documents?type=table" \
-H "Authorization: Bearer $TOKEN"
Права (scopes)
У каждого токена есть набор прав. Эндпоинт требует конкретное право; если его нет
— вернётся 403.
| Право | Что разрешает |
|---|---|
sheets.read | читать документы и значения ячеек |
sheets.write | записывать значения, работать с листами |
sheets.webhooks | создавать и удалять вебхуки |
sheets.crossbook.read | чтение между книгами |
sheets.agent.write | запись от имени агента |
Выдавайте токену только те права, которые нужны интеграции — это снижает риск при утечке.
Границы доступа
Токен не даёт больше прав, чем есть у пользователя, который его создал. Доступ к конкретному документу проверяется по тем же правилам, что и в приложении: если у пользователя нет доступа к таблице — токен тоже её не увидит.
В списке документов (GET /documents) каждая таблица содержит поле permission
— вашу роль: owner (владелец), edit (редактор), comment (комментатор) или
view (только просмотр). Писать в таблицу можно при роли owner или edit; при
comment/view запись вернёт 403.
Чтобы сразу получить только таблицы, доступные для записи, добавьте фильтр
?permission=edit — он вернёт документы, где вы владелец или редактор:
curl "https://app.coverse.team/api/v1/documents?type=table&permission=edit" \
-H "Authorization: Bearer $TOKEN"
Ограничение токена таблицами
По умолчанию токен работает со всеми вашими таблицами. При создании ключа в настройках (раздел «Автоматизация и API») можно ограничить его доступ конкретными таблицами — включите «Доступ только к выбранным таблицам» и отметьте нужные. Это снижает риск при утечке токена и позволяет выдать интеграции доступ только к тем таблицам, с которыми она работает.
Для ограниченного токена:
GET /documentsвозвращает только разрешённые таблицы;- обращение к таблице вне списка (чтение, запись, листы, вебхуки, аудит) вернёт
403, даже если у вас самих есть к ней доступ.
Безопасное хранение
- Храните токен в переменных окружения или в защищённом хранилище секретов, а не в коде и не в репозитории.
- Не передавайте токен на сторону браузера/клиента — только на своём сервере.
- Если токен скомпрометирован — отзовите его в настройках и создайте новый.
- Для разных интеграций заводите разные токены — так проще отозвать один, не ломая остальные.
Отозвать токен можно в списке ключей кнопкой «Отозвать»:
Ошибки авторизации
401— токен отсутствует или недействителен.403— у токена нет нужного права, либо действие не разрешено тарифом.
Полный список кодов ошибок — в Справочнике API.