Escopos das chaves
Um escopo indica uma parte da API que uma chave pode chamar. Cada endpoint da referência da API declara
o único escopo de que precisa. Uma requisição com uma chave que não o tem é recusada com 403 e o código
api_keys.scope, antes que qualquer coisa seja lida ou alterada.
Os escopos dizem quais operações uma chave pode chamar. A função, o perfil de dados e as coleções da chave continuam
decidindo quais objetos essas operações enxergam: uma chave com cards:write e a função viewer não pode alterar
cartões, e uma chave limitada a uma coleção não vê as outras.
Escopos
| Escopo | Permite |
|---|---|
cards:read | Ler cartões, coleções e pastas. |
cards:write | Criar, alterar e excluir cartões, coleções e pastas. |
search | Buscar na base de conhecimento (POST /v1/search). |
ask | Fazer perguntas ao assistente (POST /v1/ask, POST /v1/chat). |
import:write | Gravar nas fontes personalizadas da organização: sincronizações, lotes e exclusões, e ler o estado delas. Criar uma fonte e as chaves dela exige admin. |
webhooks:manage | Gerenciar webhooks e ler o feed de eventos (GET /v1/webhook-events). As duas coisas também exigem a função admin. |
users:read | Ler usuários e grupos. |
users:write | Alterar usuários e grupos. |
analytics:read | Ler as análises. |
audit:read | Ler o registro de auditoria. |
finance:read | Ler relatórios financeiros, faturas e pagamentos. |
catalog:read | Ler o catálogo de serviços. |
files:read | Ler arquivos gerados, como respostas exportadas. |
files:write | Alterar e excluir arquivos gerados. |
permissions:manage | Conceder e revogar permissões sobre objetos. |
admin | As configurações da organização e as chaves de API dela. Uma chave com admin também tem todos os outros escopos. |
A busca e as perguntas são, pelo sentido, leituras: uma chave que só pode ler também pode buscar e perguntar.
Escolha dos escopos
Conceda os escopos que uma integração usa e nada além disso:
| Integração | Escopos |
|---|---|
| Bot de perguntas e respostas em uma ferramenta de chat | search, ask |
| Importação a partir do seu sistema de documentos | cards:write (API de cartões) ou import:write (fonte personalizada) |
| Exportação para um data warehouse | cards:read, users:read e webhooks:manage para o feed de eventos |
| Provisionamento de usuários a partir do seu sistema de RH | users:write |
Passe a lista ao criar a chave:
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"]}'Escopos anteriores
As chaves criadas antes da divisão dos escopos continuam funcionando. Os escopos read, write e admin delas
equivalem a estes conjuntos:
| Escopo anterior | Significa |
|---|---|
read | cards:read, search, ask, users:read, analytics:read, finance:read, catalog:read, files:read |
write | tudo o que está em read, mais cards:write, files:write, users:write, permissions:manage |
admin | todos os escopos |
Uma chave criada sem escopos explícitos os recebe da sua função: admin recebe admin; editor e verifier recebem
write; viewer recebe read.
Como ver os escopos de uma chave
GET /v1/me retorna os escopos da chave que faz a requisição, quaisquer que sejam os
escopos dela. Para uma chave criada sem escopos explícitos, esses são os escopos anteriores da função dela, como
read e write; a tabela acima mostra o que eles representam. Quando uma operação falha com api_keys.scope,
error.message informa o escopo que faltou.