Autenticação

Toda requisição à API do Sursa leva uma chave de API, ou um token de acesso OAuth de um aplicativo, no cabeçalho Authorization:

Authorization: Bearer kb_3f9c…

A chave identifica a organização e decide o que a requisição pode ver e alterar: a função, os escopos, o perfil de dados e as coleções dela. No endereço da API não há sessões nem cookies. Cada requisição é autenticada por si só, então você pode enviar requisições em paralelo e de vários servidores com a mesma chave.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"

Integrações mais antigas podem enviar a chave em um cabeçalho X-API-Key. Ele continua sendo aceito, mas o código novo deve usar Authorization: Bearer.

Tipos de credenciais

Credencial	Formato	Onde funciona
Chave de API da organização	`kb_…`	Em todos os endpoints da API, dentro da função, dos escopos, do perfil de dados e das coleções dela.
Chave de fonte personalizada	`kbsrc_…`	Só nos endpoints de envio da própria fonte personalizada (`/v1/push/sources/{source_id}/…`).
Token de acesso OAuth	`kbat_…`	Nos endpoints da referência da API, dentro dos escopos do token. Um token de `POST /oauth/token` obtido com um código de autorização age em nome do colaborador que deu o consentimento; um token `client_credentials` age pela organização, como uma chave de API. Ele vale por 1 hora.

Todas são enviadas da mesma forma. Uma chave de fonte personalizada não pode ler, buscar nem alterar nada fora da fonte dela; use-a quando a chave fica guardada com terceiros, como uma plataforma de integração.

Erros de autenticação

Status e código	O que significa	O que fazer
`401` `auth.not_authenticated`	Não há chave, a chave foi digitada errado ou foi revogada.	Confira o cabeçalho e o valor da chave.
`401` `api_keys.expired`	A chave passou da data de expiração.	Crie uma chave nova e substitua a antiga.
`401` `sources.push_key_invalid`	A chave de uma fonte personalizada está errada, foi revogada ou pertence a outra fonte.	Confira a chave e o ID da fonte no caminho.
`401` `oauth.token_expired`	O token de acesso OAuth expirou.	Obtenha um novo com o token de atualização.
`403` `api_keys.scope`	A chave não tem escopo para esta operação.	Acrescente o escopo ou use uma chave que o tenha.
`403` `api_keys.feature_disabled`	O plano da organização não inclui chaves de API.	Fale com o administrador da organização.
`403` `api_keys.ip_not_allowed`	A requisição vem de um endereço fora dos endereços permitidos da chave.	Faça a chamada de uma rede permitida ou altere os endereços da chave.
`403` `api_keys.mcp_only`	Uma chave MCP pessoal foi usada fora do endpoint `/mcp`.	Use uma chave de API da organização para a API.
`403` `oauth.operation_not_allowed`	A operação não faz parte da API pública, por isso um token OAuth não pode chamá-la.	Use uma operação da referência da API.
`403` `org.suspended`	A organização está suspensa. Os dados dela são mantidos.	Fale com o administrador da organização.

403 significa que a requisição foi autenticada, mas não é permitida. Um objeto que a chave não tem permissão para ver responde 404, como um objeto que não existe, e assim uma chave não consegue descobrir o que está fora do acesso dela.

Como agir como um perfil de dados

Uma chave com a função admin pode verificar o que outro grupo de pessoas veria: o cabeçalho X-View-As executa uma requisição como um perfil de dados e, se você quiser, como uma função.

curl "https://api.sursa.com/v1/cards?limit=20" \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "X-View-As: employee:viewer"

As requisições nesse modo só leem: qualquer alteração retorna 403 com o código view_as.read_only. Um token OAuth, ou uma chave sem a função admin, não pode usar X-View-As: a resposta é 403 com o código view_as.admin_key_required. Um cabeçalho que não indica nenhum perfil existente responde 400 com o código view_as.invalid_header.

Aplicativos de navegador

A API permite requisições de qualquer origem web (Access-Control-Allow-Origin: *) e nunca usa cookies, então uma página pode chamá-la com fetch. A chave fica então na página e é visível para quem a usa. Chame a API pelo navegador só com uma chave que você aceite mostrar a esses usuários, como uma chave viewer limitada a coleções públicas, ou coloque o seu próprio servidor entre o navegador e o Sursa.

O que só um colaborador pode fazer

Uma chave de API da organização age pela organização, não por uma pessoa. Duas partes da API pertencem a pessoas, por isso só funcionam com um token que age em nome de um colaborador: uma sessão no Sursa ou um token de acesso OAuth emitido com o consentimento do colaborador.

As conversas pertencem a uma pessoa. Uma chave de API da organização vê em GET /v1/conversations só as conversas que ela mesma iniciou. A API pública não tem nenhuma operação que inicie uma conversa, então para uma chave a lista normalmente fica vazia, e as conversas dos colaboradores nunca aparecem para ela. Perguntas sem conversa, com POST /v1/ask ou POST /v1/chat, funcionam com qualquer chave que tenha o escopo ask. Para listar as conversas de um colaborador e ler o histórico de uma delas com GET /v1/conversations/{conv_id}, chame a API com um token OAuth em nome desse colaborador. O token vê só as conversas do próprio colaborador; qualquer outra conversa responde 404 com o código conversations.not_found.

Só um colaborador verifica um cartão. A verificação confirma que uma pessoa conferiu o conteúdo, por isso POST /v1/cards/{card_id}/verification/verify e POST /v1/cards/{card_id}/verify exigem uma sessão ou um token OAuth em nome de um colaborador que possa verificar o cartão. Com uma chave de API da organização, ou um token client_credentials, eles respondem 400 com o código cards.verify_user_account_required. As conferências habituais vêm antes: um cartão que a chave não pode ver responde 404, e uma chave que não tem permissão para verificá-lo recebe 403.