Autenticação
A Diska tem dois mecanismos de autenticação, para dois usos diferentes:
| Uso | Mecanismo | Superfície |
|---|---|---|
| Integrações (o seu código a falar com a Diska) | Chave API dsk_… | Canal API — https://api.diska.ai/v1 |
| Backoffice (pessoas a usar app.diska.ai) | Sessão Better Auth (JWT) | API interna — /api/v1 |
Chaves API (Canal API)
As chaves API são geridas em Definições → Chaves API e autenticam o Canal API — a superfície REST pública em https://api.diska.ai/v1. Cada chave tem nome, descrição opcional, pré-visualização mascarada, âmbitos opcionais (sem âmbitos = acesso total), expiração opcional, data de criação e último uso, e pode ser revogada a qualquer momento.
A chave é enviada num destes cabeçalhos:
Authorization: Bearer dsk_…
X-API-Key: dsk_…
Uma chave actua apenas sobre os dados da própria organização — leituras (agentes, chamadas, análises, números, conhecimento) e as escritas que os seus âmbitos permitirem (criar/publicar agentes, ingestão de conhecimento, gestão de webhooks); não é aceite em nenhum endpoint interno de /api/v1. Consulte Chaves API para a gestão e Canal API para os endpoints.
Sessões do backoffice (Better Auth)
O início de sessão em app.diska.ai é feito pelo serviço de identidade da Diska, construído sobre Better Auth. Depois do login, o backoffice envia em cada pedido à API interna um JWT de curta duração, assinado assimetricamente e verificado pela API via JWKS — nenhum segredo partilhado sai do serviço de identidade:
Authorization: Bearer <jwt>
X-Organization-Id: <organization_id>
Selecção de organização
Um utilizador pode pertencer a várias organizações. A organização activa é determinada pelo cabeçalho X-Organization-Id; o backoffice lista as organizações do utilizador e regista a troca:
GET /api/v1/organizations
POST /api/v1/organizations/switch
{
"organization_id": "<id>"
}
Papéis na organização
O acesso dentro de uma organização é definido pelo papel do membro:
| Papel | Resumo |
|---|---|
owner | Controlo total, incluindo eliminar a organização. |
admin | Definições da organização, membros, chaves API, arquivo e eliminações. |
editor | Cria, edita e publica agentes, fluxos, conhecimento e acções. |
viewer | Consulta (agentes, históricos, análises) e testes, sem alterações. |
As verificações de permissão são feitas no servidor a partir do papel; os identificadores internos de permissões não fazem parte do contrato público.
Erros de autenticação
| Código | Significado |
|---|---|
| 401 | Credencial ausente, inválida, expirada ou revogada. |
| 403 | Sem permissão (papel ou âmbito insuficiente) ou organização suspensa. |
| 404 | Recurso inexistente ou de outra organização. |