Опсези кључа

Опсег означава део API интерфејса који кључ сме да позива. Свака операција у API референци наводи један опсег који јој је потребан. Захтев са кључем који га нема одбија се са 403 и кодом api_keys.scope, пре него што се било шта прочита или промени.

Опсези одређују које операције кључ сме да позива. Улога кључа, профил приступа и колекције и даље одлучују које објекте те операције виде: кључ са cards:write и улогом viewer не може да мења картице, а кључ ограничен на једну колекцију не види остале.

Опсези

Опсег	Дозвољава
`cards:read`	Читање картица, колекција и фолдера.
`cards:write`	Креирање, измену и брисање картица, колекција и фолдера.
`search`	Претрагу базе знања (`POST /v1/search`).
`ask`	Питања асистенту (`POST /v1/ask`, `POST /v1/chat`).
`import:write`	Упис у сопствене изворе организације: синхронизације, пакете и брисања, и читање њиховог стања. За креирање извора и његових кључева потребан је `admin`.
`webhooks:manage`	Управљање вебхуковима и читање фида догађаја (`GET /v1/webhook-events`). За оба је потребна и улога `admin`.
`users:read`	Читање корисника и група.
`users:write`	Измену корисника и група.
`analytics:read`	Читање аналитике.
`audit:read`	Читање дневника ревизије.
`finance:read`	Читање финансијских извештаја, фактура и плаћања.
`catalog:read`	Читање каталога сервиса.
`files:read`	Читање генерисаних фајлова, на пример извезених одговора.
`files:write`	Измену и брисање генерисаних фајлова.
`permissions:manage`	Доделу и опозив дозвола на објектима.
`admin`	Подешавања организације и њених API кључева. Кључ са `admin` има и све остале опсеге.

Претрага и питања по својој природи спадају у читање: кључ који сме само да чита може и да претражује и да поставља питања.

Избор опсега

Доделите опсеге које интеграција користи и ништа више:

Интеграција	Опсези
Бот за питања и одговоре у апликацији за ћаскање	`search`, `ask`
Увоз из вашег система за документе	`cards:write` (API за картице) или `import:write` (сопствени извор)
Извоз у складиште података	`cards:read`, `users:read` и `webhooks:manage` за фид догађаја
Аутоматско додавање корисника из вашег HR система	`users:write`

Проследите листу када креирате кључ:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support bot", "role": "viewer", "scopes": ["search", "ask"]}'

Ранији опсези

Кључеви креирани пре него што су опсези подељени и даље раде. Њихови опсези read, write и admin означавају ове скупове:

Ранији опсег	Значење
`read`	`cards:read`, `search`, `ask`, `users:read`, `analytics:read`, `finance:read`, `catalog:read`, `files:read`
`write`	све из `read`, плус `cards:write`, `files:write`, `users:write`, `permissions:manage`
`admin`	сви опсези

Кључ креиран без изричито наведених опсега добија их према својој улози: admin добија admin; editor и verifier добијају write; viewer добија read.

Преглед опсега кључа

GET /v1/me враћа опсеге кључа који шаље захтев, без обзира на то које опсеге кључ има. За кључ креиран без изричито наведених опсега то су ранији опсези његове улоге, као што су read и write; табела изнад показује шта они обухватају. Када операција не успе са api_keys.scope, error.message наводи опсег који је недостајао.