Chaves de API e escopos

Toda requisição à API do Sursa é feita com uma chave de API da sua organização. Uma chave pertence à organização, e não a uma pessoa: ela continua funcionando quando o colaborador que a criou sai da empresa, e o que ela pode fazer é definido na própria chave.

O que uma chave pode fazer

Três configurações de uma chave decidem o que uma requisição feita com ela pode ver e alterar. Cada uma só restringe as outras.

Configuração	O que ela controla
Role (função)	`admin`, `editor`, `verifier` ou `viewer`, as mesmas funções que as pessoas têm. A chave pode fazer o que um usuário com essa função pode fazer.
Scopes (escopos)	Quais partes da API a chave pode chamar, por exemplo `cards:read` ou `webhooks:manage`. Veja Escopos das chaves.
Data profile (perfil de dados)	Opcional. Limita a chave às categorias de conhecimento que o perfil permite, como um usuário com esse perfil.

Uma chave também pode ser limitada a algumas coleções e receber uma data de expiração. Uma requisição fora desses limites falha: a falta de um escopo retorna 403 com o código api_keys.scope, e um objeto que a chave não pode ver retorna 404, exatamente como se não existisse.

Dê a cada integração uma chave própria, com a função e os escopos mais restritos de que ela precisa. Um job de sincronização que só grava documentos não precisa de admin; um job de relatórios não precisa de escopos de escrita.

Criar uma chave

Um administrador da organização cria chaves no Sursa em Administration → API keys (administração, chaves de API) ou com POST /v1/api-keys, usando uma chave ou uma sessão com a função 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"
  }'

A resposta traz o valor da chave em key. Ele é mostrado uma única vez: o Sursa guarda só um hash dele e não pode mostrá-lo de novo. Uma chave tem o formato kb_ seguido de 43 caracteres; os primeiros caracteres (prefix) aparecem na lista de chaves, para que você consiga distingui-las.

Sem scopes, a chave recebe os escopos da sua função. Passe scopes para restringi-la ainda mais. Sem expires_at, a chave não expira.

Manter as chaves em segredo

Guarde as chaves em um gerenciador de segredos ou nas variáveis de ambiente do seu serviço, nunca no código-fonte.
Use as chaves só nos seus servidores. O Sursa aceita requisições de navegadores (o CORS está aberto), mas uma chave em uma página web fica visível para todos que a abrem.
Nunca envie uma chave em uma URL. Envie-a só no cabeçalho Authorization.
Se uma chave vazar, revogue-a imediatamente e crie uma nova.

Verificar uma chave

GET /v1/me retorna a chave, a função, os escopos efetivos, o perfil de dados, a expiração e o limite de taxa dela. Ele funciona com qualquer chave válida, quaisquer que sejam os escopos dela, então use-o como teste de conexão da sua integração e quando investigar um 403.

Rotacionar uma chave

A rotação substitui uma chave sem parar a integração. O jeito mais rápido é rotacionar a própria chave: POST /v1/api-keys/{key_id}/roll emite um valor novo para a mesma chave, com a mesma função, os mesmos escopos, as mesmas coleções e a mesma data de expiração. O valor anterior continua funcionando durante overlap_hours (24 horas por padrão, até 168), para que você implante o valor novo nesse meio-tempo; POST /v1/api-keys/{key_id}/revoke-previous encerra a sobreposição antes do prazo.

Para substituir uma chave por outra diferente:

Crie uma chave nova com a mesma função, os mesmos escopos e o mesmo perfil de dados.
Implante a chave nova na sua integração.
Acompanhe a chave antiga em Administration → API keys (ou last_used em GET /v1/api-keys) até que ela não seja mais usada.
Revogue a chave antiga.

Defina uma data de expiração nas chaves e faça a rotação antes dela. O Sursa avisa os administradores da organização antes de uma chave expirar; uma chave expirada retorna 401 com o código api_keys.expired.

Revogar uma chave

Revogue uma chave em Administration → API keys ou com DELETE /v1/api-keys/{key_id}. A revogação entra em vigor em poucos segundos em todos os servidores da API. As requisições com uma chave revogada retornam 401 com o código auth.not_authenticated.

Chaves de uma fonte personalizada

Uma fonte personalizada tem um tipo próprio de chave. Ela começa com kbsrc_, só pode gravar documentos nessa fonte e não pode ler nem buscar nada. É a chave mais segura para entregar a uma plataforma de integração como o Zapier. Crie-a na página da fonte, em API keys (chaves de API da fonte), ou com POST /v1/sources/{source_id}/push-keys.

Quando as chaves não estão disponíveis

As chaves de API fazem parte do plano da organização. Se o plano não as inclui, criar uma chave e qualquer requisição com uma chave retornam 403 com o código api_keys.feature_disabled.