Токен базы данных Baserow: создание и права доступа к API
Токен базы данных - это постоянный ключ доступа к REST API Baserow: он заменяет логин и пароль в скриптах, внешних приложениях и автоматизациях, а его права можно ограничить конкретным рабочим пространством и набором операций - создание, чтение, изменение или удаление строк.
Обзор
В отличие от сессии, которая завершается при выходе из аккаунта, токен базы данных действует до тех пор, пока его не отзовут вручную. Это делает его основным способом подключить к Baserow внешний скрипт, серверное приложение или интеграцию, которой нужно читать и писать данные таблиц через REST API без участия человека в каждом запросе. Токен привязывается к одному рабочему пространству и работает только с данными строк - создать, изменить или удалить саму структуру таблицы (поля, представления) через токен базы данных нельзя.
Токен базы данных или JWT
Baserow с открытым исходным кодом использует два способа аутентификации API, и у них разное назначение:
| Способ | Срок действия | Типичное применение | Область доступа |
|---|---|---|---|
| Токен базы данных | Бессрочно, до отзыва | Внешние приложения, автоматизации, длительно работающие скрипты | Только данные строк |
| JWT-токен | Около 7 минут | Разработка, короткие тестовые запросы | Полный доступ к аккаунту |
Ключевое отличие: токен базы данных позволяет только читать и изменять данные строк таблицы. Если нужно создавать, менять или удалять саму структуру таблицы - поля, представления, саму таблицу, - потребуется JWT-токен, который получают через обычный вход в аккаунт.
Права доступа токена
Каждому токену можно задать до четырёх независимых прав:
| Право | Что разрешает | Типичный эндпоинт API |
|---|---|---|
| Create | Добавлять новые строки (включает право на чтение) | POST /api/database/rows/table/{table_id}/ |
| Read | Просматривать существующие данные | GET к эндпоинтам строк |
| Update | Изменять существующие строки (включает право на чтение) | PATCH к эндпоинтам строк |
| Delete | Удалять строки | DELETE к эндпоинтам строк |
Права назначаются на уровне рабочего пространства, но можно ограничить токен конкретными базами данных или таблицами внутри него - тогда он не сможет обращаться к остальным данным того же рабочего пространства.
Как создать токен базы данных
- Откройте настройки аккаунта и перейдите на вкладку Database tokens («Токены базы данных»).
- Нажмите Create token +, укажите понятное название токена и выберите рабочее пространство, к которому он будет привязан.
- Ограничьте область действия конкретными базами данных или оставьте полный доступ ко всем базам рабочего пространства, затем настройте права create, read, update и delete.
- Сгенерируйте токен, сразу скопируйте его значение и сохраните в надёжном месте - открыть его повторно после закрытия диалога не получится.
Управление существующими токенами
Из меню ⋮ рядом с названием токена доступны следующие действия:
- Копирование - скопировать значение токена через значок копирования, не создавая новый.
- Регенерация - выпустить новое значение токена для того же набора прав; прежнее значение сразу становится недействительным, что удобно, если токен мог попасть в чужие руки.
- Переименование - изменить название токена без влияния на его права и работоспособность.
- Удаление - отозвать токен полностью, если он больше не нужен.
Как использовать токен в запросах к API
Передайте значение токена в заголовке Authorization каждого запроса к REST API:
Authorization: Token YOUR_DATABASE_TOKEN_HEREПример запроса на чтение строк таблицы:
curl -H "Authorization: Token YOUR_DATABASE_TOKEN_HERE" \
-H "Content-Type: application/json" \
https://your-baserow-domain/api/database/rows/table/{table_id}/Идентификатор таблицы {table_id} для этого URL берётся из адресной строки Baserow или из документации API - подробнее об этом в статье «Идентификаторы базы данных и таблицы»
. Полный список эндпоинтов, форматов ответа и примеров запросов на разных языках - в статье «REST API Baserow»
.
Что важно знать перед созданием токена
- Токен привязывается к одному рабочему пространству - для работы с несколькими пространствами понадобится отдельный токен на каждое.
- После закрытия диалога создания значение токена больше нигде не показывается целиком - только регенерация выдаст новое значение взамен утраченного.
- На self-hosted развёртывании открытого Baserow ограничений на частоту запросов к API по умолчанию нет - в отличие от облачного сервиса Baserow, где действует лимит на одновременные запросы.
- Если задача - реагировать на изменения данных сразу, как только они происходят, а не опрашивать API самостоятельно, для этого лучше подходят вебхуки , а не периодические запросы с токеном.
Часто задаваемые вопросы
Чем токен базы данных отличается от обычного входа в аккаунт? Вход в аккаунт даёт временный JWT-токен и полный доступ ко всем действиям в интерфейсе, включая изменение структуры таблиц. Токен базы данных постоянный, но ограничен только операциями с данными строк - создать, прочитать, изменить или удалить.
Может ли один токен работать с несколькими базами данных? Да, если при создании токена не сужать область действия до конкретной базы - тогда токен получит доступ ко всем базам данных выбранного рабочего пространства с заданными правами create, read, update и delete.
Что делать, если токен скомпрометирован? Немедленно откройте меню токена и выберите регенерацию - прежнее значение перестанет работать сразу, а новое нужно будет сохранить и обновить во всех местах, где использовался старый токен.
Нужен ли токен базы данных для настройки вебхука? Нет, вебхуки настраиваются отдельно через интерфейс базы данных и не требуют токена для получения уведомлений - токен нужен, когда внешнее приложение само обращается к Baserow за данными или для их изменения.
Следующий шаг - статья «REST API Baserow» : полный список эндпоинтов для чтения и записи данных таблиц.