Integre ao login do seu sistema
API REST autenticada por aplicação. Cadastre a empresa, confirme o pagamento e crie uma aplicação no painel. Guarde as duas chaves no backend, nunca no navegador do usuário final.
1. Avaliar um acesso
Use a chave de avaliação em Authorization: Bearer SUA_CHAVE, JSON e um Idempotency-Key exclusivo por evento. A base é a mesma origem deste painel.
POST /v1/access/evaluations
Authorization: Bearer SUA_CHAVE
Idempotency-Key: evento_00000001
Content-Type: application/json
{
"subject_id": "usuario_0001",
"session_id": "sessao_00001",
"device_id": "dispositivo_0001",
"action": "view_dashboard",
"primary_authenticated": true,
"authenticated_at": "2026-09-29T10:00:00Z",
"authentication_method": "passkey"
}O horário acima é ilustrativo: envie o instante real da autenticação verificada pelo seu servidor. Identificadores e idempotência: 8–128 caracteres ASCII, letras minúsculas (a–z), números, traço ou sublinhado. Gere pseudônimos canônicos, como hashes hexadecimais minúsculos; não transforme IDs distintos do seu sistema em um mesmo pseudônimo. Não envie dados pessoais diretos ou segredos. O identificador do dispositivo deve ser vinculado à sessão pelo backend, não aceito cegamente do navegador.
Ações: view_dashboard, view_account, login, failed_login, change_bank_account, account_recovery, enroll_factor, payment. Métodos: password, email_otp, sms_otp, totp, passkey. Para falha de login, use primary_authenticated: false, com horário e método nulos. O método informado neste evento é uma declaração do seu backend: a avaliação de risco não verifica o desafio do seu provedor. Para verificação TOTP pela CLP, use a integração MFA descrita abaixo.
2. Interpretar a resposta
recommended_action: continue_existing_session, require_step_up, review ou deny. A resposta inclui decision_id, mode, enforceable, reason_codes, signal_quality, policy_version, evaluated_at, expires_at, app_id, subject_id, session_id, device_id, action, allowed_methods.
Observação (shadow) nunca dispensa o desafio atual. Ative a política pelo painel depois de testar sua integração. Em modo ativo, a continuidade exige dispositivo confiável e autenticação recente com passkey ou TOTP; isso não equivale a uma probabilidade de fraude. TOTP não oferece a mesma resistência a phishing que passkeys. Ações sensíveis sempre exigem confirmação adicional. Cinco falhas em 15 minutos resultam em recusa recomendada.
3. Consumir uma decisão ativa
Antes de aplicá-la, envie o mesmo contexto e um identificador exclusivo da operação. Uma decisão não pode ser usada em outra operação. O ERP deve executar a operação também de forma idempotente usando este identificador.
POST /v1/access/evaluations/DECISION_ID/consume
Authorization: Bearer SUA_CHAVE
Content-Type: application/json
{
"subject_id": "usuario_0001",
"session_id": "sessao_00001",
"device_id": "dispositivo_0001",
"action": "view_dashboard",
"operation_id": "operacao_00000001"
}Consumo aceita apenas decisão ativa, válida e da versão atual. Repetir o mesmo consumo é idempotente. Mudar contexto, operação ou política, revogar o dispositivo ou ultrapassar a validade pode gerar 409. A validade máxima é 60 segundos, limitada pelo prazo da autenticação. O campo enforceable não significa “acesso autorizado”: aplique a recomendação retornada.
4. Dispositivos e feedback
Após verificação forte recente no seu backend, use a chave administrativa para POST /v1/admin/devices com subject_id, device_id, verification_method, verified_at. São aceitos passkey/TOTP verificados nos últimos cinco minutos. A confiança dura 30 dias. Revogue por DELETE /v1/admin/devices/{subject}/{device}. A chave de avaliação não pode criar confiança.
Envie POST /v1/access/evaluations/{id}/feedback com {"outcome":"challenge_passed"}. Outros resultados: challenge_failed, confirmed_compromise, confirmed_legitimate, unknown. Resultados confirmados exigem chave administrativa. O primeiro feedback é imutável; repetição igual é aceita. Feedback nunca cria confiança. Desafio aprovado não comprova legitimidade.
5. Consultas, limites e falhas
GET /v1/access/evaluations/{id}: resultado por até 30 dias.GET /v1/access/usage: consumo da empresa; aviso em 80% e 100%.GET /v1/access/capabilities: modo, limites e versão.GET /v1/admin/report: agregados da aplicação.
Avaliação nova: 201. Mesma idempotência e mesmo corpo: 200 com a decisão original, sem renovar validade ou consumir de novo. Corpo diferente: 409. Após 30 dias, replay retorna 410; identificadores de idempotência ficam protegidos por até 90 dias. Não reutilize chaves antigas.
20.000 avaliações por mês de calendário UTC, compartilhadas entre até três aplicações. 120 requisições/minuto por aplicação. 16 KB por corpo. Campos desconhecidos são rejeitados. 400: entrada inválida; 401: chave ausente, inválida, revogada, vencida ou conta sem vigência; 403: permissão; 404: recurso não encontrado neste escopo; 409: conflito; 413: corpo grande; 429: limite; 5xx: indisponibilidade. Nunca converta erro, timeout ou resultado vencido em baixo risco. Preserve a autenticação habitual e recuse ações sensíveis se o fallback não puder ser aplicado.
Na rotação pelo painel, a chave anterior é revogada imediatamente. Cada chave vale até um ano. A desativação da aplicação revoga ambas as chaves. Não envie chaves em URLs, logs, telas ou chamados.
6. Relatórios com IA
Solicitados no painel, com quatro requisições aceitas/mês por empresa e mínimo de dez avaliações. Apenas contagens de recomendações e resultados seguem ao Gemini. A análise é assíncrona, pode falhar e não altera a política. Consulte novamente o painel para acompanhar. Não inclua dados de usuários em nomes de aplicações ou chamados.
7. Operação
Confirme autenticação do seu backend, isolamento por aplicação, requisições concorrentes, fallback, revogação e reversão de política antes de ativar. O modo ativo é uma política de regras, não um modelo estatístico antifraude calibrado. Não há SLA individual nesta oferta. Para suporte: contato@clpsistemas.com.br.
8. MFA com aplicativo autenticador
Acrescente uma confirmação TOTP ao login do usuário do seu ERP. A CLP oferece a etapa hospedada de cadastro e confirmação; seu backend continua responsável pela autenticação primária, pela autorização e pela conclusão da operação. Esta jornada é diferente do acesso administrativo ao painel CLP.
- Seu backend autentica a pessoa e avalia o acesso.
- Cria uma sessão MFA com os identificadores e horários verificados no servidor.
- A pessoa abre a etapa hospedada e informa o código do aplicativo.
- Seu backend consulta e consome a confirmação; só então aplica sua autorização e conclui a operação de forma idempotente.
Disponibilidade: o módulo precisa estar habilitado para o serviço e a conta precisa manter acesso à API. Consulte GET /public/mfa/capabilities para conferir enabled e os recursos disponíveis. Se retornar mfa_unavailable, mantenha a exigência de segundo fator e não conclua a operação protegida. Não converta indisponibilidade, recuperação ou revogação em aprovação.
Criar a sessão no backend
POST /v1/mfa/sessions
Authorization: Bearer CHAVE_DA_APLICACAO_NO_BACKEND
Content-Type: application/json
{
"kind": "verify",
"subject_id": "usuario_0001",
"session_id": "sessao_0001",
"device_id": "dispositivo_0001",
"action": "payment",
"operation_id": "operacao_0001",
"decision_id": "ID_DA_DECISAO_DE_RISCO",
"primary_authenticated_at": "INSTANTE_UTC_REAL",
"primary_expires_at": "VENCIMENTO_UTC_REAL"
}Use a chave de avaliação ou administrativa da mesma aplicação. Os horários são marcadores: envie ISO 8601 UTC real. A CLP confia na declaração de autenticação primária do backend integrador; nunca a preencha diretamente com dados do navegador. A resposta contém session_id da sessão MFA, hosted_url e expires_at. Guarde no backend a associação com a sessão primária. O fator é isolado por empresa, aplicação e usuário.
Abra a URL hospedada sem registrá-la em logs ou analytics. O fragmento contém um token temporário de uso restrito. A página o remove da URL e não recebe sua chave de API. O prazo de verify também respeita o vencimento da decisão de risco, que pode ser de até 60 segundos; as demais jornadas têm prazo máximo de cinco minutos, limitado pela sessão primária.
Cadastro, troca e recuperação
| Jornada | O que a pessoa faz | Resultado |
|---|---|---|
enroll | Adiciona QR/chave manual ao autenticador e confirma um código. | Fator cadastrado e dez códigos de recuperação, exibidos uma vez. |
verify | Confirma um código do autenticador cadastrado. | Confirmação para consulta e consumo no backend. |
replace | Confirma o autenticador atual, cadastra e confirma o novo. | Substituição; o fator anterior permanece até a confirmação. |
recover | Usa um código de recuperação e cadastra um novo autenticador. | Recadastro; não autoriza uma operação de negócio. |
revoke | Confirma o autenticador atual. | Revogação do fator, sem dispensar as exigências do ERP. |
Cada código de recuperação é de uso único. A pessoa pode copiar ou salvar o lote antes de concluir. Consultas posteriores não exibem os códigos novamente. Cancelar ou deixar vencer uma troca pendente preserva o fator anterior; um código de recuperação já consumido não volta a ficar disponível.
Conferir o resultado
GET /v1/mfa/sessions/ID_DA_SESSAO_MFA
Authorization: Bearer CHAVE_DA_APLICACAO_NO_BACKEND
POST /v1/mfa/sessions/ID_DA_SESSAO_MFA/consume
Authorization: Bearer CHAVE_DA_APLICACAO_NO_BACKEND
Content-Type: application/json
{
"subject_id": "usuario_0001",
"session_id": "sessao_0001",
"device_id": "dispositivo_0001",
"action": "payment",
"operation_id": "operacao_0001",
"decision_id": "ID_DA_DECISAO_DE_RISCO"
}A consulta retorna kind, state, expires_at, proof_ready e o identificador da sessão MFA. Somente verify permite consumir uma confirmação. O consumo confere o contexto original e retorna verified, method, factor_version, verified_at, context, policy_version. É de uso único e não produz uma recomendação de permitir acesso. Seu backend deve manter sua autorização e idempotência; a tela de sucesso, por si só, não libera uma operação. A integração deve exigir decisão aplicável em modo active, com enforceable: true, contexto e prazo válidos. deny mantém a recusa; shadow não autoriza a operação mesmo com TOTP confirmado. Estes endpoints não ativam MFA automaticamente nas integrações legadas.
Estados da página: awaiting_code, awaiting_confirmation, completed, cancelled, expired, invalidated. completed também ocorre em cadastro e recuperação, por isso não o trate como prova de uma operação. Se uma resposta se perder, consulte o estado; não reenvie códigos ou operações automaticamente.
Até cinco tentativas por sessão, além do limite persistido por usuário/aplicação. invalid_code permite nova tentativa dentro do orçamento; mfa_rate_limited exige espera. session_expired, session_invalidated, session_consumed encerram aquela jornada. mfa_storage_unavailable e mfa_key_unavailable mantêm a operação sem confirmação. A revogação da chave que criou a sessão invalida o fluxo hospedado.
Proteções operacionais padrão por aplicação: 5.000 registros de fator, incluindo revogados; 1.000 sessões não expiradas; 50.000 marcadores de operações consumidas e 100.000 eventos de auditoria MFA, ambos com retenção de 30 dias. São limites técnicos configuráveis, sem alteração do plano comercial. Capacidade esgotada retorna mfa_capacity_reached (503) e não libera a operação.
A limpeza é tentada a cada cinco minutos e na criação de sessão: remove sessões e segredos temporários expirados, contadores de limite vencidos, consumos e auditoria MFA com mais de 30 dias. Preserva o contador antirreplay do fator. O marcador de consumo impede nova confirmação da mesma operação por 30 dias; seu ERP deve manter sua própria idempotência. Uma confirmação verificada vence para consumo em até 30 segundos, também limitada pela sessão e decisão.
A origem hospedada exige HTTPS em produção. HTTP loopback é permitido somente nos ambientes Testing e Development. Erros de infraestrutura MFA exigem recusar a operação protegida.
QR, chave de configuração e códigos pertencem somente a esta jornada de segurança. Não os envie como eventos de risco, feedback, relatórios de IA ou chamados. TOTP não é resistente a phishing e não assina os detalhes da operação; o vínculo é conferido no backend. Este módulo não oferece SMS, passkeys, diretório de usuários ou SSO.