Auth21 Kernel
Inicio Entrar

Auth21 Kernel | Developers

Documentacao para Desenvolvedores

Contrato tecnico da Auth21: endpoints, sessao, tokens, modos de identidade, revogacao, npx @auth21/js install @auth21/js e checklist real para integrar com seguranca em qualquer stack.

SDK oficial

npx @auth21/js install @auth21/js

First Success

Onboarding em minutos

Comece por Hosted com npx @auth21/js install @auth21/js e copie um caminho oficial com callback, token exchange, userinfo e sessao local, sem adivinhar PKCE ou state.

Abrir onboarding tecnico

SDK JS

Pacote oficial do fluxo hosted

@auth21/js cobre state, PKCE, URL de /authorize, token exchange e /userinfo para o caminho de first success.

Ver install e uso

Core OAuth

Fluxo e contrato

Veja o caminho real de /authorize, /token, /userinfo e como o authorization_code se conecta a sessao.

Abrir contrato OAuth

Sessao E Token

Revogacao e validade real

Entenda identity_session, rotacao de refresh, reuse detection e porque o JWT nao vive sozinho.

Ver ciclo de vida

Modos

Escolha o modo certo

Hosted, Bridge, Client embed e QR solo com a diferenca tecnica de cada um.

Comparar modos

Verification

Challenge fora do login puro

Entenda quando sair de /two-factor/* e usar /verification/* para qualquer acao sensivel da sua aplicacao.

Ver camada de verificacao

First Success tecnico

A Auth21 ja tem OAuth, Hosted, Bridge e 2FA. O objetivo do First Success e reduzir o tempo entre criei a aplicacao e meu login esta funcionando, sem o integrador descobrir state, PKCE, callback, token exchange e sessao local por conta propria.

SDK oficial do First Success

O caminho atual comeca por npx @auth21/js install @auth21/js e usa o pacote @auth21/js como SDK oficial para Hosted OAuth, callback, token exchange e /userinfo.

  • Hosted em 10 minutos: docs/FIRST_SUCCESS_HOSTED_10_MIN.md
  • Next.js: docs/FIRST_SUCCESS_NEXTJS_10_MIN.md
  • Laravel: docs/FIRST_SUCCESS_LARAVEL_10_MIN.md
  • NestJS: docs/FIRST_SUCCESS_NESTJS_10_MIN.md
  • Bridge: docs/FIRST_SUCCESS_BRIDGE_10_MIN.md

Introducao tecnica

Esta e a documentacao tecnica da Auth21 Kernel. Aqui o foco nao e explicar o produto; e mostrar o contrato real de integracao, o ciclo de vida de sessao e token, os modos de identidade e os pontos que mais quebram em implementacao.

OAuth contract

  • Fluxo principal: /authorize -> callback -> /token -> /userinfo.
  • response_type=code e o caminho principal.
  • client_secret deve ficar no backend.
  • PKCE com S256 deve ser tratado como padrao do fluxo moderno.
  • redirect_uri precisa ser identica no authorize e no token exchange.

/authorize

Orquestra o inicio do fluxo, resolve modo de identidade, cria ou retoma pending_authorization, reaproveita sessao quando possivel e decide o proximo passo.

Parametros essenciais

client_id, redirect_uri, response_type=code, scope, state, code_challenge, code_challenge_method.

Responsabilidades internas

  • resolver identity_mode, entry_mode e effective_flow_mode
  • criar ou retomar pending_authorization
  • reaproveitar identity_session valida
  • gerar authorization_code no final do fluxo

/token

Faz o exchange do authorization_code e a rotacao do refresh token.

  • Valida client_secret e o contexto do request.
  • Confere code_verifier contra o code_challenge.
  • Bloqueia reuso do authorization code.
  • Emite access_token, refresh_token e opcionalmente id_token.
  • Reuso de refresh token mata a familia e a sessao raiz.

/userinfo

Valida bearer token, assinatura, expiracao, audience e sessao ainda ativa. Nao trata JWT como suficiente por si so: o sid precisa continuar valido na base.

Revoke e logout-session

  • /revoke invalida token e derruba a arvore ligada a ele quando aplicavel.
  • /logout-session revoga a sessao global via cookie ou id_token_hint.
  • O centro da revogacao e a identity_session.

Sessions and tokens

identity_session: ancora a validade operacional do login.

authorization_code: curto, single-use e ligado a sessao.

refresh_token: rotacionado por familia.

access_token: JWT assinado; ainda depende da sessao continuar ativa para passar no /userinfo.

Modos de identidade

Hosted

A Auth21 autentica e cria a sessao diretamente.

Bridge

Seu sistema autentica e devolve prova assinada para a Auth21.

Client embed

O cliente autentica no proprio dominio e afirma a sessao via /client-session-assert.

QR solo

Desktop inicia, mobile aprova e o backend finaliza em OAuth padrao.

Verification Layer

Quando o mesmo motor de challenge precisa sair do login puro e ser reutilizado em troca de senha, alteracao de email, admin action ou qualquer acao sensivel, a camada tecnica recomendada passa a ser /verification/*.

  • POST /verification/challenge
  • POST /verification/verify
  • POST /verification/approve
  • GET /verification/status

Mail2FA no contrato tecnico

O 2FA por email continua sendo a camada hosted de prova por email da Auth21. No contrato tecnico, a app decide quando chamar challenge e verify; a Auth21 cuida do envio, das paginas hosted e da validacao.

  • POST /two-factor/challenge
  • POST /two-factor/verify
  • GET /two-factor/verify-page
  • GET /two-factor/authorize-page

Trust Center no produto

O Trust Center nao muda o contrato OAuth. Ele consolida operacao: readiness, ultima Sandbox, ultima publicacao e config drift. Para o integrador, isso reduz o custo de descobrir se a app esta realmente pronta para producao.

Session Center no produto

O Session Center opera a camada de identidade ja emitida. Ele usa a tabela real de auth21_identity_session para listar sessoes ativas, exibir source, device_id, auth_ip e permitir revogacao individual ou em lote por subject.

Contrato de seguranca

  • Use state e valide no callback.
  • Use PKCE S256.
  • Nao exponha client_secret no browser.
  • Valide origem de iframe/postMessage quando usar embed.
  • Assine Bridge e asserts no backend, nunca no JS publico.

Errores e troubleshooting

  • invalid_grant: callback divergente, PKCE errado ou code reutilizado.
  • invalid_state: perda do estado entre start e callback.
  • A21-AU-002: redirect URI nao autorizada.
  • A21-FZ-003: fluxo aguardando aprovacao mobile.

Checklist de producao

  1. Integration Check e Sandbox sem falha critica.
  2. PKCE e callback validados em staging.
  3. Revogacao e logout-session funcionando.
  4. Refresh rotation e reuse detection verificados.
  5. Logs com trace_id observaveis.