Autenticação

Endpoints de autenticação e gerenciamento de sessão da Plataforma Keeptor.

Fluxo básico

1. Login (/login): usuário envia email + password (+ organization_id opcional se pertencer a múltiplas organizações)
2. A API retorna access_token (validade 1 hora) e refresh_token
3. Cliente armazena os tokens com segurança no escopo da sessão
4. Toda chamada subsequente envia Authorization: Bearer <access_token>
5. Antes do access_token expirar, cliente chama /refresh para obter um novo
6. /logout encerra a sessão. A revogação é imediata: os demais endpoints passam a responder 401 para aquele token. Sair é idempotente: chamar /logout de novo com o mesmo token responde 200 com data.already_ended: true
7. /switch-org: para usuários multi-organização, cria uma sessão nova na organização alvo

Boas práticas para o cliente

• Renove de forma proativa: monitore a expiração do token e chame /refresh antes de receber 401
• Trate 401 de forma uniforme: qualquer 401 significa sessão inválida: limpe o estado local e redirecione para o login
• Não tente reutilizar um access_token após logout, porque ele já está revogado
• Não trafegue tokens em logs nem em URLs (só em headers)

Toda resposta de erro segue o schema ErrorResponse. Mostre ao usuário o message; para reconhecer o erro no seu código, use error.key, que não muda com o idioma nem com o texto. error.code está sempre presente; error.field aponta o campo que causou o erro (para exibir a mensagem embaixo dele); error.internal descreve a regra para o suporte. Exemplo real:

{
  "success": false,
  "message": "E-mail ou senha incorretos.",
  "error": {
    "type": "INVALID_CREDENTIALS",
    "code": "INVALID_CREDENTIALS",
    "message": "E-mail ou senha incorretos.",
    "key": "gateway.auth.invalid_credentials",
    "params": {},
    "field": null,
    "internal": "Login recusado: e-mail ou senha não conferem. Responde 401."
  }
}

Os endpoints de autenticação respondem antes (ou durante a troca) da sessão. Por isso o message sai sempre em português: traduza na sua interface pela error.key.

Do ponto de vista do cliente, todo 401 significa "sessão inválida": renove pelo /refresh ou refaça o login.

Verificar uma permissão

Para saber se o usuário logado tem uma permissão (por exemplo, para mostrar ou esconder uma ação na tela), use o POST /data, operação call:

{ "mode": "structured", "operation": "call", "function": "fc_core_authorize", "args": { "p_permission": "filtro.compartilhar" } }

{ "success": true, "message": "Operacao concluida", "data": true }

• O usuário e a organização são sempre os do token: não há parâmetro de usuário nem de organização (qualquer outro parâmetro retorna 400).
• data é true quando o usuário tem a permissão e false quando não tem.
• Permissão que a organização ainda não exige responde true.
• Permissão inexistente ou inativa responde false.
• A resposta serve para a tela. A regra continua sendo aplicada no servidor quando a operação é executada.