Ключи API и области

Каждый запрос к Sursa API выполняется с ключом API вашей организации. Ключ принадлежит организации, а не человеку: он продолжает работать, когда создавший его сотрудник уходит, а то, что ключ может делать, задаётся в самом ключе.

Что разрешено ключу

Три настройки ключа определяют, что запрос с ним может видеть и менять. Каждая из них только сужает остальные.

Настройка	Что определяет
Роль	`admin`, `editor`, `verifier` или `viewer` — те же роли, что у людей. Ключ может делать то же, что пользователь с этой ролью.
Области	Какие части API ключ может вызывать, например `cards:read` или `webhooks:manage`. См. Области ключа.
Профиль доступа	Необязательно. Ограничивает ключ теми категориями знаний, которые разрешает профиль, как у пользователя с этим профилем.

Ключ можно также ограничить отдельными коллекциями и задать ему срок действия. Запрос за пределами этих ограничений не выполняется: при недостающей области возвращается 403 с кодом api_keys.scope, а объект, который ключ не видит, возвращает 404 — точно так же, как если бы его не было.

Давайте каждой интеграции отдельный ключ с самой узкой ролью и только теми областями, которые ей нужны. Заданию синхронизации, которое только записывает документы, не нужен admin; заданию отчётности не нужны области записи.

Как создать ключ

Администратор организации создаёт ключи в Sursa в разделе Администрирование → API-ключи или через POST /v1/api-keys с ключом или сессией, у которых роль admin:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

Ответ содержит значение ключа в key. Оно показывается один раз: Sursa хранит только его хеш и показать ключ снова не может. Ключ выглядит как kb_ и 43 символа после него; первые символы (prefix) видны в списке ключей, чтобы ключи можно было различать.

Без scopes ключ получает области своей роли. Передайте scopes, чтобы сузить их ещё больше. Без expires_at ключ бессрочный.

Как хранить ключи

Храните ключи в менеджере секретов или в переменных окружения своего сервиса, но никогда — в исходном коде.
Пользуйтесь ключами только со своих серверов. Sursa принимает запросы из браузеров (CORS открыт), но ключ на веб-странице виден каждому, кто её открывает.
Никогда не передавайте ключ в URL. Передавайте его только в заголовке Authorization.
Если ключ утёк, сразу отзовите его и создайте новый.

Как проверить ключ

GET /v1/me возвращает ключ, его роль, действующие области, профиль доступа, срок действия и лимит частоты запросов. Он работает с любым действующим ключом, какие бы области у того ни были, поэтому используйте его для проверки подключения своей интеграции и при разборе ошибки 403.

Как сменить ключ

Смена ключа заменяет его, не останавливая интеграцию. Быстрее всего перевыпустить ключ: POST /v1/api-keys/{key_id}/roll выпускает новое значение того же ключа с той же ролью, областями, коллекциями и сроком действия. Прежнее значение продолжает работать в течение overlap_hours (по умолчанию 24 часа, не больше 168), так что за это время можно установить новое значение; POST /v1/api-keys/{key_id}/revoke-previous досрочно завершает перекрытие.

Чтобы вместо этого заменить ключ другим:

Создайте новый ключ с той же ролью, областями и профилем доступа.
Установите новый ключ в свою интеграцию.
Следите за старым ключом в разделе Администрирование → API-ключи (или за last_used в GET /v1/api-keys), пока им не перестанут пользоваться.
Отзовите старый ключ.

Задавайте ключам срок действия и меняйте их до его окончания. Sursa предупреждает администраторов организации до того, как срок ключа истечёт; ключ с истёкшим сроком возвращает 401 с кодом api_keys.expired.

Как отозвать ключ

Отзовите ключ в разделе Администрирование → API-ключи или через DELETE /v1/api-keys/{key_id}. Отзыв вступает в силу за секунды на всех серверах API. Запросы с отозванным ключом возвращают 401 с кодом auth.not_authenticated.

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

У своего источника есть особый вид ключей. Такой ключ начинается с kbsrc_, может только записывать документы в этот один источник и ничего не может читать или искать. Это самый безопасный ключ, который можно передать платформе интеграций вроде Zapier. Создайте его на странице источника в разделе Ключи API или через POST /v1/sources/{source_id}/push-keys.

Если ключи недоступны

Ключи API входят в тариф организации. Если тариф их не включает, создание ключа и любой запрос с ключом возвращают 403 с кодом api_keys.feature_disabled.