API ключове и обхвати

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

Какво има право да прави ключът

Три настройки на ключа решават какво може да вижда и да променя заявка с него. Всяка от тях само стеснява останалите.

Настройка	Какво определя
Роля	`admin`, `editor`, `verifier` или `viewer` – същите роли, каквито имат хората. Ключът може да прави онова, което може потребител с тази роля.
Обхвати	Кои части на API може да извиква ключът, например `cards:read` или `webhooks:manage`. Вж. Обхвати на ключовете.
Профил за достъп	Незадължителен. Ограничава ключа до категориите знания, които профилът позволява, както при потребител с този профил.

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

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

Създаване на ключ

Администраторът на организацията създава ключове в Sursa в Administration → API keys (администриране, 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 прекратява припокриването по-рано.

Ако вместо това искате да замените ключа с друг:

Създайте нов ключ със същата роля, обхвати и профил за достъп.
Внедрете новия ключ в интеграцията си.
Следете стария ключ в Administration → API keys (или last_used в GET /v1/api-keys), докато спре да се използва.
Анулирайте стария ключ.

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

Анулиране на ключ

Анулирайте ключ в Administration → API keys или с DELETE /v1/api-keys/{key_id}. Анулирането влиза в сила до няколко секунди на всеки сървър на API. Заявките с анулиран ключ връщат 401 с кода auth.not_authenticated.

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

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

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

API ключовете са част от плана на организацията. Ако планът не ги включва, създаването на ключ и всяка заявка с ключ връщат 403 с кода api_keys.feature_disabled.