API кључеви и опсези

Сваки захтев ка API интерфејсу платформе Sursa шаље се са 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.