Documentation

Primeiros Passos

Authagonal fornece a cada tenant um servidor OIDC totalmente em conformidade com os padrões. Cada tenant recebe sua própria URL de emissor, documento de discovery e endpoints de token — sem infraestrutura compartilhada entre tenants. Você pode ir do zero a um fluxo de login funcionando em menos de 5 minutos.

Crie um Tenant

Cadastre-se em authagonal.io e escolha um slug para seu tenant. O slug se torna seu domínio emissor: {slug}.authagonal.io. Após criar sua conta, verifique seu endereço de e-mail para ativar o tenant.

Escolha um slug único para seu tenant durante o cadastro

Registre um Cliente

Navegue até Clientes na barra lateral do portal e clique em Criar. Insira um clientId e clientName para seu aplicativo. Em seguida, configure pelo menos uma URI de redirecionamento — é para onde os usuários são enviados após a autenticação. Por exemplo: https://app.example.com/callback.

Registre um novo cliente OAuth no portal

Seu Primeiro Login

A maneira mais rápida de integrar é com oidc-client-ts, uma biblioteca leve de cliente OIDC para aplicações JavaScript e TypeScript.

import { UserManager } from 'oidc-client-ts';

const mgr = new UserManager({
  authority: 'https://acme.authagonal.io',
  client_id: 'my-app',
  redirect_uri: 'https://app.example.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
});

// Redirect to login
mgr.signinRedirect();

// On callback page
const user = await mgr.signinRedirectCallback();
console.log(user.profile); // { sub, email, name, ... }

Se você preferir uma abordagem mínima sem biblioteca, pode usar o fluxo padrão de authorization code do OAuth 2.0 com fetch simples:

// 1. Redirect the user to the authorization endpoint
const authorizeUrl = new URL('https://acme.authagonal.io/connect/authorize');
authorizeUrl.searchParams.set('client_id', 'my-app');
authorizeUrl.searchParams.set('redirect_uri', 'https://app.example.com/callback');
authorizeUrl.searchParams.set('response_type', 'code');
authorizeUrl.searchParams.set('scope', 'openid profile email');
authorizeUrl.searchParams.set('code_challenge', codeChallenge);
authorizeUrl.searchParams.set('code_challenge_method', 'S256');
window.location.href = authorizeUrl.toString();

// 2. On the callback page, exchange the code for tokens
const res = await fetch('https://acme.authagonal.io/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: new URLSearchParams(window.location.search).get('code')!,
    redirect_uri: 'https://app.example.com/callback',
    client_id: 'my-app',
    code_verifier: codeVerifier,
  }),
});

const tokens = await res.json();
// tokens.id_token, tokens.access_token, tokens.refresh_token

A página de login padrão do seu tenant

Painel

O painel do portal oferece uma visão geral em tempo real do seu tenant. Ele apresenta as métricas mais importantes — crescimento de usuários, atividade de autenticação e navegação rápida para todos os recursos do portal.

Visão Geral

No topo do painel, você verá uma mensagem de boas-vindas junto com a contagem total atual de usuários. Abaixo, um gráfico de Usuários Ativos Diários exibe um histórico de 7 dias de usuários únicos que se autenticaram a cada dia, dando uma visão rápida das tendências de engajamento.

A tela inicial do painel com gráfico de DAU e visão geral de atividades

Métricas de Atividade

O painel de métricas de atividade exibe quatro cartões de estatísticas resumindo os principais eventos de autenticação:

• Logins Bem-sucedidos — total de fluxos de autenticação concluídos
• Logins Falhos — credenciais incorretas, contas bloqueadas ou rejeições de política
• Usuários Ativos — usuários únicos que se autenticaram no período selecionado
• Operações SCIM — eventos de provisionamento de usuários e grupos de IdPs conectados

Use os filtros de intervalo de tempo para alternar entre 24 horas, 3 dias, 7 dias e 30 dias. Todos os cartões de estatísticas e gráficos são atualizados para refletir a janela selecionada.

Métricas de atividade com intervalo de tempo configurável

Navegação Rápida

Abaixo do painel de métricas, cartões de navegação levam diretamente a cada recurso principal: Clientes, Usuários, Grupos, Funções, SSO, SCIM, Marca e Configurações. Cada cartão mostra uma breve descrição para que novos membros da equipe possam se orientar rapidamente.

Clientes

Clientes OAuth representam os aplicativos que autenticam usuários através do seu tenant. Cada cliente tem sua própria configuração de URIs de redirecionamento, escopos, tipos de concessão, tempos de vida de token e política de MFA.

Lista de Clientes

A página de Clientes exibe uma tabela de todos os clientes registrados. Cada linha mostra o clientId, nome de exibição, tipos de concessão permitidos como badges coloridos e se o PKCE está habilitado. Clique em qualquer linha para abrir o editor de configuração completo.

Lista de clientes com badges de tipo de concessão e indicadores de PKCE

Criando um Cliente

Clique em Criar Cliente para registrar um novo aplicativo. Você precisa fornecer dois campos:

• clientId — um identificador único para o cliente (ex: my-spa)
• clientName — um nome de exibição legível

Registre um novo cliente OAuth

Excluindo um Cliente

Para excluir um cliente, abra a configuração do cliente e clique no botão Excluir Cliente na parte inferior da página. Você será solicitado a confirmar antes que o cliente seja permanentemente removido. Todas as sessões ativas e tokens do cliente excluído são imediatamente invalidados.

Referência de Configuração do Cliente

Cada cliente possui um conjunto abrangente de opções de configuração organizadas em várias seções.

Configurações Gerais

URIs

Os campos de URI usam entrada por tags — digite um valor e pressione Enter ou vírgula para adicioná-lo. Clique no X de qualquer tag para removê-la.

Campos de entrada por tags para configurar URIs

Escopos e Tipos de Concessão

Tempos de Vida de Token

Configure tempos de vida de token por cliente

URIs de logout

Clientes podem registrar URIs de logout tanto back-channel quanto front-channel. Ambas são opcionais — configure as que correspondam à forma como seu aplicativo limpa sua sessão.

Política de MFA

Cada cliente pode substituir a política de MFA do tenant com uma configuração por cliente. O dropdown de política de MFA oferece três opções:

Substituição de política de MFA por cliente

SSO Empresarial

O SSO Empresarial permite que seus clientes tragam seu próprio provedor de identidade. Authagonal suporta federação SAML 2.0 e OIDC com roteamento baseado em domínio, para que os usuários sejam automaticamente direcionados ao IdP correto com base no endereço de e-mail.

Roteamento SSO baseado em domínio

Conexões SAML 2.0

Para criar uma conexão SAML, navegue até a página SSO e selecione a aba SAML. Forneça o seguinte:

Quando você salva a conexão, Authagonal busca o documento de metadados e importa o certificado de assinatura do IdP, a URL do endpoint SSO e o formato do identificador de nome. Os metadados são atualizados periodicamente para capturar rotações de certificado.

Crie uma conexão SSO SAML 2.0

Conexões OIDC

Para criar uma conexão de federação OIDC, selecione a aba OIDC e forneça:

Crie uma conexão de federação OIDC

Roteamento de Domínio

O roteamento de domínio redireciona automaticamente os usuários para o provedor de identidade correto com base no domínio de e-mail. Quando um usuário insere seu e-mail na página de login, Authagonal verifica se a parte do domínio (ex: acme.com) corresponde a alguma conexão SSO configurada. Se corresponder, o usuário é redirecionado de forma transparente para o IdP da sua organização.

O roteamento de domínio mapeia domínios de e-mail para provedores de identidade

Provisionamento JIT

Por padrão, quando um usuário faz login via SSO pela primeira vez e ainda não existe no seu tenant, Authagonal cria sua conta automaticamente (provisionamento Just-In-Time). Isso pode ser desabilitado por conexão marcando Desabilitar provisionamento JIT ao criar ou editar a conexão.

Quando o provisionamento JIT está desabilitado, apenas usuários que foram pré-provisionados — via SCIM, pela página de Usuários do portal ou pela API — podem fazer login através dessa conexão. Usuários desconhecidos recebem um erro access_denied e são orientados a contatar seu administrador.

Usuários

A página de Usuários permite gerenciar todos os usuários finais do seu tenant. Você pode buscar usuários, visualizar seus detalhes, criar novas contas e ver como cada usuário foi provisionado.

Busca e Paginação

A barra de busca suporta filtragem por endereço de e-mail ou ID de usuário. A busca tem debounce de 300ms, então os resultados são atualizados conforme você digita sem sobrecarregar a API. Os resultados são paginados em 50 usuários por página — use os controles de navegação na parte inferior da tabela para navegar entre as páginas.

Tabela de Usuários

A tabela de usuários exibe as seguintes colunas para cada usuário:

A lista de usuários com barra de busca e paginação

Criando Usuários

Clique em Criar Usuário para adicionar um novo usuário local. O formulário requer:

Crie um novo usuário local

Detalhes do usuário

Clique em qualquer linha da lista de usuários para abrir sua página de detalhes. A partir daí você pode editar dados do perfil, gerenciar funções, redefinir MFA, revisar atributos personalizados e excluir o usuário.

Perfil

Edite e-mail, nome/sobrenome, telefone, empresa, ID externo e a flag de ativo do usuário. Alterações de e-mail devem permanecer únicas no tenant; a API retorna email_in_use se já estiver em uso.

Funções

Atribua e remova funções definidas na página Funções. A associação a funções aparece nos tokens ID e de acesso quando o cliente tem includeRolesInTokens ativado.

Autenticação multifator

Veja todas as credenciais MFA registradas para o usuário — aplicativo autenticador (TOTP), WebAuthn/passkeys e códigos de recuperação — cada um com timestamps de registro e último uso. Remova credenciais individuais ou redefina toda a MFA. Redefinir força o usuário a se registrar novamente no próximo login.

Atributos personalizados

Dados arbitrários chave/valor anexados ao usuário. As chaves devem ser únicas. Os atributos são expostos via API de perfil de usuário e SCIM, e podem ser mapeados para claims do token de acesso configurando os userClaims de um scope personalizado.

Excluir usuário

Remove permanentemente o usuário e todas as suas credenciais MFA. Digite o e-mail do usuário para confirmar — não há como desfazer.

Grupos

Grupos permitem organizar usuários e incluir membros de grupo em tokens. Grupos podem ser criados manualmente no portal ou provisionados automaticamente via SCIM a partir de um provedor de identidade externo.

Lista de Grupos

A página de Grupos mostra todos os grupos do seu tenant com as seguintes informações:

Lista de grupos com indicadores de origem

Criando um Grupo

Clique em Criar Grupo e insira um displayName para o grupo. Nomes de grupos devem ser descritivos e únicos dentro do seu tenant (ex: "Engenharia", "Admins de Faturamento", "Testadores Beta").

Detalhes do Grupo e Membros

Clique em qualquer grupo para abrir a visualização detalhada. Aqui você pode ver todos os membros atuais e gerenciar a associação:

• Adicionar membros — Insira um ID de usuário para adicionar um usuário ao grupo.
• Remover membros — Clique no botão de remover ao lado de qualquer membro para removê-lo individualmente.

Gerencie membros do grupo na visualização detalhada

Grupos em Tokens

Quando includeGroupsInTokens está habilitado em um cliente, o token de ID inclui uma claim groups contendo as associações de grupo do usuário. Cada entrada inclui o id e name do grupo:

{
  "sub": "user-123",
  "email": "jane@acme.com",
  "groups": [
    { "id": "grp-001", "name": "Engineering" },
    { "id": "grp-002", "name": "Beta Testers" }
  ]
}

Funções

Funções suportam controle de acesso baseado em funções (RBAC) no seu aplicativo. Defina funções no Authagonal, atribua-as a usuários e use a claim roles em tokens para aplicar autorização na lógica do seu aplicativo.

Gerenciando Funções

A página de Funções exibe uma tabela de todas as funções definidas com edição inline. Cada função possui:

Criando uma Função

Clique em Criar Função e forneça um nome e descrição. Nomes de funções devem ser concisos e seguir uma convenção de nomenclatura consistente no seu aplicativo (ex: minúsculas com hífens: billing-admin).

Edição Inline

Funções suportam edição inline diretamente na tabela. Clique no ícone de lápis em qualquer função para entrar no modo de edição — os campos de nome e descrição se tornam editáveis. Modifique os valores e clique no ícone de confirmação para salvar. As alterações entram em vigor imediatamente.

Excluindo uma Função

Clique no ícone de exclusão em qualquer função para removê-la. Você será solicitado a confirmar antes que a função seja permanentemente excluída. Remover uma função não invalida retroativamente tokens existentes — a função estará ausente dos novos tokens emitidos após a exclusão.

Edição inline de funções na tabela de funções

Funções em Tokens

Funções atribuídas a um usuário são incluídas como uma claim roles no token de ID. Seu aplicativo pode ler esta claim para tomar decisões de autorização:

{
  "sub": "user-123",
  "email": "jane@acme.com",
  "roles": ["admin", "billing-admin"]
}

Provisionamento SCIM

SCIM 2.0 (System for Cross-domain Identity Management) permite provisionamento automático de usuários e grupos a partir de provedores de identidade empresariais como Okta, Azure AD, OneLogin e JumpCloud. Quando configurado, contas de usuários e associações de grupos são automaticamente sincronizadas do IdP upstream para seu tenant Authagonal.

Sincronização de ciclo de vida de usuário SCIM com provisionamento downstream

Etapas de Configuração

Siga estas etapas para habilitar o provisionamento SCIM para um cliente:

1. Selecione o aplicativo cliente — Escolha o cliente OAuth ao qual o provisionamento SCIM será associado.
2. Gere um token SCIM — Forneça uma descrição e um período de expiração em dias, depois gere o token.
3. Copie o token imediatamente — O valor bruto do token é exibido apenas uma vez. Copie-o antes de fechar o diálogo.
4. Configure seu IdP — Nas configurações SCIM do seu provedor de identidade, insira a URL base e o token bearer.
5. Teste a sincronização de usuários — Acione uma sincronização de teste do seu IdP e verifique se os usuários aparecem no portal Authagonal.

URL Base SCIM

Configure seu provedor de identidade com a seguinte URL base:

https://{slug}.authagonal.io/scim/v2

Substitua {slug} pelo slug do seu tenant.

Página de configuração SCIM com geração de token

Gerenciamento de Tokens

Tokens SCIM autenticam requisições de provisionamento do seu IdP. Você pode gerenciar múltiplos tokens por cliente:

Para revogar um token, clique no botão Revogar ao lado dele. Tokens revogados permanecem visíveis na lista para fins de auditoria, mas imediatamente param de aceitar requisições.

Gerenciamento de tokens com indicadores de tokens ativos e revogados

Testando Conectividade

Verifique se sua integração SCIM está funcionando consultando o endpoint ServiceProviderConfig:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://acme.authagonal.io/scim/v2/ServiceProviderConfig

Uma resposta bem-sucedida retorna um documento JSON descrevendo os recursos SCIM suportados, incluindo operações em lote, filtragem e capacidade de alteração de senha.

Scopes OAuth

Os scopes permitem que clientes solicitem partes específicas dos dados ou permissões de um usuário. O Authagonal suporta tanto scopes padrão OIDC quanto scopes personalizados que você define para suas APIs.

Scopes integrados

Scopes personalizados

Defina seus próprios scopes na página Scopes. Cada scope descreve uma permissão ou recurso que um cliente pode solicitar (por exemplo, billing.read, orders.write).

Claims personalizados nos tokens

Claims personalizados têm duas metades. A fonte são dados por usuário: cada AuthUser tem um dicionário customAttributes que você pode preencher via Portal (Usuários → usuário → Atributos personalizados), via SCIM ou via um hook de provisionamento TCC. A liberação é por scope: a lista userClaims de cada scope nomeia as chaves permitidas a sair do servidor.

Quando um cliente solicita scopes, o Authagonal percorre os scopes concedidos, une suas listas userClaims e emite apenas essas chaves dos customAttributes do usuário. Chaves desconhecidas são silenciosamente descartadas — um cliente não pode ler um atributo adivinhando o nome. Claims OIDC padrão (sub, email, name, etc.) seguem a especificação e não estão sujeitos à whitelist.

# 1. On the user (Portal → Users → {user} → Custom Attributes)
department = "engineering"
employee_id = "E-1042"
seat_tier = "enterprise"

# 2. On a custom scope (Portal → Scopes → projects.read)
name        = "projects.read"
userClaims  = ["department", "seat_tier"]   # <-- whitelist

# 3. Client requests scope=openid projects.read
# Decoded access token (relevant fields only):
{
  "sub": "u-9b…",
  "scope": "openid projects.read",
  "department": "engineering",
  "seat_tier":  "enterprise"
  // employee_id is NOT emitted — it's not in the whitelist for any granted scope.
}

Atribuindo scopes a clientes

Adicione scopes permitidos na aba Clientes → Scopes e Grants. Um cliente só pode solicitar scopes que lhe foram concedidos; scopes desconhecidos são rejeitados com invalid_scope.

Marca

Personalize a aparência das páginas de login do seu tenant. As configurações de marca permitem combinar a experiência de autenticação com a identidade visual do seu produto — desde logotipos e cores até substituições avançadas de CSS.

Aparência

Configurações de aparência com visualização de cores em tempo real

Informações de Contato

Opções da Página de Login

Controle quais elementos aparecem na página de login do seu tenant:

Exemplo de página de login com marca personalizada aplicada

CSS personalizado

Para controle total sobre a aparência da página de login, forneça a URL de um arquivo CSS nas configurações de marca. O arquivo é carregado após os estilos padrão, então suas regras têm prioridade.

Modo escuro

O app de login inclui temas claro, escuro e do sistema. Os usuários escolhem em um seletor na página de login; a escolha persiste entre sessões. Quando em system, a SPA acompanha prefers-color-scheme em tempo real.

Valores claros são declarados em :root; substituições escuras ficam restritas a .dark. O branding do tenant via customCssUrl sempre prevalece — suas cores permanecem independentemente do tema do usuário.

Configurações

Configure políticas de segurança, webhooks e configurações de ambiente em todo o tenant. Estas configurações se aplicam globalmente a todos os clientes, a menos que sejam substituídas no nível do cliente.

Política de Senha

Defina os requisitos de complexidade de senha para todos os usuários do seu tenant:

Configuração de política de senha

Política de MFA

A política de MFA do tenant define o comportamento padrão de autenticação multifator. Clientes individuais podem substituir esta configuração.

Sessão e Bloqueio

Controle a duração da sessão e o comportamento de bloqueio de conta:

Configuração de sessão e bloqueio

Webhooks

Webhooks permitem reagir a eventos de autenticação em tempo real. Dois eventos (onUserAuthenticated, onTokenIssued) são aplicáveis — por padrão disparam de forma assíncrona e não bloqueiam o usuário, mas você pode ativar a aplicação por evento para que uma resposta não 2xx ou um corpo {"allow": false} rejeite a ação. Os demais eventos são notificações — sempre fire-and-forget, nunca bloqueiam.

Configurações adicionais de webhook:

Configuração de eventos de webhook

Verificar webhooks

Assim que qualquer URL de webhook é configurada, o Authagonal gera um segredo de assinatura por tenant (um valor whsec_… exibido somente leitura em Configurações → Webhooks). Cada entrega de saída traz um cabeçalho X-Authagonal-Signature: t=<unix>,v1=<hex>, onde v1 é HMAC-SHA256(secret, "{t}.{body}") calculado sobre o corpo bruto da requisição. Recalcule-o no seu endpoint e compare em tempo constante para confirmar que a requisição realmente veio do Authagonal e não foi adulterada — e rejeite entregas cujo t seja antigo demais para bloquear repetições.

import crypto from 'node:crypto';

// rawBody MUST be the exact bytes Authagonal sent — verify before any JSON re-serialization.
function verifyAuthagonalWebhook(signatureHeader, rawBody, signingSecret) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
  const { t, v1 } = parts;

  // Replay protection: reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Janela de Manutenção

Defina uma janela de manutenção preferida para operações disruptivas, como rotações de certificado e atualizações de infraestrutura. Escolha uma hora UTC (0–23) — o portal também exibe o horário equivalente no seu fuso horário local por conveniência.

Ambiente Sandbox

O ambiente sandbox é um clone completo do seu tenant de produção, disponível em uma URL separada. Use-o para testar alterações de configuração, integrações SSO e endpoints de webhook sem afetar usuários em produção.

O sandbox está acessível em {slug}-sandbox.authagonal.io.

Controles do ambiente sandbox

Faturamento

Gerencie sua assinatura e faturamento pela página de Faturamento do portal. Esta página oferece uma visão geral do seu plano atual e fornece acesso ao portal de faturamento do Stripe para gerenciar métodos de pagamento, faturas e alterações de plano.

Informações da Assinatura

A página de faturamento exibe os detalhes da sua assinatura atual de forma resumida. Você verá um badge de status indicando o estado da sua assinatura — active, trialing, past_due, canceled ou unpaid — junto com o nome do plano, o período de faturamento atual (datas de início e fim) e se sua assinatura está configurada para cancelar no final do período atual.

Gerenciar Assinatura

Clique no botão Gerenciar Assinatura para abrir o portal de faturamento do Stripe em uma nova janela. De lá, você pode atualizar seus métodos de pagamento, visualizar e baixar faturas, alterar seu plano ou cancelar sua assinatura.

Se nenhuma assinatura existir ainda, um call-to-action Configurar Faturamento é exibido, que o guia na seleção de um plano e inserção dos dados de pagamento.

A página de faturamento exibe os detalhes da assinatura atual e fornece acesso ao Stripe

Domínios Personalizados

Sirva suas páginas de autenticação a partir do seu próprio domínio (ex: auth.seudominio.com) em vez do padrão {slug}.authagonal.io. Domínios personalizados proporcionam aos seus usuários uma experiência de autenticação contínua e com sua marca.

Adicionando um Domínio

Insira o hostname que deseja usar no formulário de adição de domínio (ex: auth.seudominio.com). Após adicionado, o domínio aparecerá na sua lista de domínios com o status pending_verification.

Verificação de DNS

Crie um registro CNAME apontando seu domínio para {slug}.authagonal.io. Quando o registro DNS estiver configurado, clique em Verificar para checar a propagação de DNS.

auth.yourdomain.com.  CNAME  acme.authagonal.io.

Certificados TLS

Quando seu domínio for verificado, você precisará de um certificado TLS para que os usuários possam se conectar com segurança via HTTPS. Authagonal suporta duas opções:

Automático (cert-manager) — Authagonal provisiona e renova certificados TLS automaticamente usando cert-manager. Esta é a opção recomendada para a maioria dos usuários. Nenhuma configuração adicional é necessária.

Traga o Seu (BYO) — Faça upload do seu próprio certificado e chave privada em formato PEM. Esta opção é útil se sua organização exige certificados de uma autoridade certificadora específica. A expiração do certificado é monitorada para que você possa renová-lo antes de expirar.

Status do Domínio

Cada domínio exibe um badge de status indicando seu estado atual: pending_verification (DNS ainda não confirmado), verified (DNS confirmado, TLS pendente), active (totalmente operacional) ou failed (problema de configuração detectado).

A lista de domínios exibe cada domínio personalizado e seu status atual

Faça upload do seu próprio certificado TLS e chave privada em formato PEM

Configuração de e-mail

Configure como seu tenant envia e-mails transacionais — verificação, redefinição de senha e notificações de MFA. Escolha entre o remetente compartilhado padrão, um domínio personalizado verificado via Resend ou seu próprio servidor SMTP.

Provedores de e-mail

Identidade do remetente

O e-mail e o nome do remetente são compartilhados entre todos os modos de provedor. O e-mail do remetente é obrigatório; o nome do remetente volta para o nome do tenant quando vazio.

Domínio personalizado Resend

Verifique seu domínio de envio com o Resend uma vez e então use-o como endereço From para este tenant. Os registros DNS TXT (SPF, DKIM) são fornecidos pela página Domínios; o Resend os valida automaticamente.

SMTP personalizado

Traga seu próprio servidor SMTP — útil para relays internos, provedores não cobertos pelo Resend ou fixação regulatória.

Domínio de envio personalizado

Ao usar o provedor Resend, você pode registrar seu próprio domínio para que os e-mails venham da sua marca (por exemplo, noreply@acme.com) em vez de @authagonal.io.

1. Vá para Configurações → E-mail e selecione o provedor Domínio personalizado Resend.
2. Digite o nome do seu domínio e clique em Registrar.
3. Adicione os registros DNS exibidos (DKIM, SPF e return path) ao DNS do seu domínio.
4. Clique em Verificar — assim que o DNS propagar (normalmente 1–10 minutos), o status do domínio mudará para verificado.

Testes

Use o botão Enviar e-mail de teste em Configurações → E-mail para verificar sua configuração. Um e-mail de teste será enviado ao endereço de administrador usando as configurações salvas.

Registro de Auditoria

O Registro de Auditoria fornece um registro somente leitura de todas as ações administrativas realizadas no seu tenant. Cada alteração feita pelo portal ou API é capturada com contexto completo, proporcionando um rastro completo para conformidade e resolução de problemas.

Colunas do Registro

Ações Rastreadas

As seguintes ações administrativas são registradas no registro de auditoria:

O registro de auditoria fornece um registro completo de todas as ações administrativas

Backups

O Authagonal faz backup automático dos dados do seu tenant a cada hora. Os backups incluem todos os usuários, grupos, funções, clientes, conexões SSO, tokens SCIM, marca e configurações. Você pode ver o histórico de backup e baixar o backup completo mais recente na página Backups.

Como os backups funcionam

• Um backup completo é executado uma vez por dia, capturando todas as tabelas do shard de armazenamento do seu tenant.
• Backups incrementais são executados a cada hora, capturando apenas as linhas que mudaram desde o último backup.
• Os backups são armazenados no Azure Blob Storage com a mesma identidade gerenciada usada pelo seu tenant.
• Registros excluídos são rastreados via tombstones e incluídos em backups para completude de auditoria.

Baixando backups

Clique em "Baixar mais recente" para obter um arquivo ZIP contendo o backup completo mais recente mesclado com todos os backups incrementais subsequentes. Cada tabela é exportada como um arquivo JSONL (um objeto JSON por linha).

Apps de Provisionamento

Apps de provisionamento recebem notificações webhook em tempo real quando usuários são criados ou autenticados no seu tenant. Isso permite que sistemas downstream configurem contas automaticamente, atribuam licenças ou sincronizem dados de usuários sem intervenção manual.

Como Funciona

Quando ocorre um evento de usuário (criação ou autenticação), Authagonal chama a URL de callback do seu app de provisionamento usando o padrão TCC (Try/Confirm/Cancel). Esta abordagem em três fases garante provisionamento confiável entre múltiplos sistemas downstream:

Payload do Webhook

Cada requisição de webhook inclui um payload JSON com os seguintes campos:

Adicionando um App de Provisionamento

Para adicionar um app de provisionamento, forneça um nome, uma URL de callback e uma chave de API opcional. A chave de API é enviada como token Bearer no cabeçalho Authorization de cada requisição de webhook, permitindo que seu app autentique requisições do Authagonal.

Testes

Clique em Testar ao lado de qualquer app de provisionamento para enviar uma requisição de teste à sua URL de callback. Os resultados do teste exibem o código de status HTTP e o corpo da resposta, ajudando você a verificar se seu app está recebendo e processando webhooks corretamente.

Teste apps de provisionamento para verificar a entrega e o tratamento de resposta de webhooks

Limites do Plano

O número máximo de apps de provisionamento é configurável por tenant, com um limite padrão de 6. Este limite pode ser ajustado por um administrador se seu fluxo de trabalho exigir alvos de provisionamento adicionais.

Equipe

A página de Equipe gerencia os administradores do portal — as pessoas que podem acessar e configurar seu tenant através do portal de gerenciamento. Todos os membros da equipe têm acesso administrativo completo a todos os aspectos da configuração do seu tenant.

Lista de Administradores

A lista de administradores exibe o nome, endereço de e-mail e data de adição de cada membro da equipe. Um indicador "Você" é exibido ao lado da linha do usuário atual para que você possa identificar facilmente sua própria conta.

Convidando Administradores

Para convidar um novo membro da equipe, forneça o endereço de e-mail, nome e uma senha temporária (mínimo de 8 caracteres). O usuário convidado faz login com a senha temporária e deve alterá-la no primeiro acesso.

Campos do convite

Convites de administrador criam um usuário totalmente provisionado — sem ida e volta de e-mail.

Removendo Administradores

Clique em Remover ao lado de qualquer membro da equipe para revogar seu acesso. Um diálogo de confirmação é exibido antes que a remoção seja finalizada. Você não pode remover a si mesmo — deve haver sempre pelo menos um administrador na equipe.

Gerencie administradores do portal na página de Equipe

Importar e migrar

Migre um sistema de identidade existente para o seu tenant Authagonal. Duas fontes são suportadas — Duende IdentityServer (um banco de dados SQL Server) e Auth0 (a Management API). Cada uma executa uma prévia somente leitura para que você revise exatamente o que será copiado antes de confirmar.

Importação do Duende IdentityServer

Migre clientes, scopes, usuários e papéis de um banco SQL Server do Duende IdentityServer existente para o seu tenant Authagonal. A importação roda em duas fases — prévia e commit — para que você revise o que será copiado antes de qualquer alteração.

O que é importado

O importador lê o ConfigurationDb do Duende e as tabelas do ASP.NET Identity e grava as linhas mapeadas no seu tenant. Artefatos de curta duração como persisted grants, device codes e chaves de assinatura são ignorados.

Prévia antes do commit

Cole sua string de conexão do ConfigurationDb / IdentityDb do Duende e clique em Executar prévia. A prévia abre uma conexão somente-leitura e conta cada linha que seria importada — nenhuma gravação ocorre.

• Contagens de entidades para clientes, scopes, usuários, papéis e atribuições de papéis.
• Colisões de proprietário — admins do tenant cujo <code>userId</code> existente difere do <code>sub</code> recebido do Duende.
• Avisos para tabelas desconhecidas e colunas não mapeadas para que você saiba o que será descartado.

Painel de prévia com contagens, colisões e avisos

Hashes de senha

O Duende armazena senhas em ASP.NET Identity V3 (PBKDF2). O PasswordHasher do Authagonal verifica esse formato diretamente e re-hasheia para o formato nativo no primeiro login bem-sucedido — os usuários mantêm suas senhas existentes sem fluxo de redefinição.

Rotação de userId do proprietário

Se o e-mail de um admin do tenant corresponder a um usuário no banco do Duende, o userId Authagonal desse admin é rotacionado para coincidir com o sub do Duende. Isso mantém tokens e entradas de auditoria consistentes após a migração. A prévia lista cada colisão antes do commit.

Executando a importação

Clique em Iniciar importação após revisar a prévia. A fase de commit grava clientes, scopes, usuários, papéis e referências de login externo nos stores do tenant. Linhas duplicadas de clientId, scope name, email e role name são ignoradas — o importador é seguro para re-executar.

O que não é importado

• Persisted grants, device codes, sessões server-side — curta duração, regenerados automaticamente.
• Chaves de assinatura — o Authagonal emite suas próprias chaves por tenant.
• Colunas e tabelas personalizadas — qualquer coisa fora do schema padrão do Duende é sinalizada como aviso para você saber que esses dados foram descartados.
• Clientes desativados — importados desativados; reative-os na página Clientes quando estiver pronto.

Importar do Auth0

Conecte a Authagonal à Management API do seu tenant Auth0 e traga suas aplicações, APIs, papéis, usuários e conexões corporativas. Os IDs de usuário e de aplicação importados são preservados, então as referências existentes de sub e client_id continuam resolvendo após o corte.

O que você vai precisar

Crie uma aplicação Machine-to-Machine no Auth0 autorizada para a Management API, com estes scopes de leitura: read:users, read:clients, read:resource_servers, read:roles, read:connections, read:client_grants. Cole o domínio, o client ID e o client secret dela no formulário de importação — eles são usados apenas para a importação.

O que é importado

Senhas

A Management API do Auth0 nunca retorna hashes de senha. Se você tiver a exportação em massa de senhas assistida pelo suporte do Auth0 (NDJSON), forneça-a — os hashes bcrypt são importados na íntegra e seus usuários mantêm as senhas sem redefinição. Esse arquivo também traz o conjunto completo de usuários, removendo o limite de 1.000 usuários da listagem da API do Auth0. Sem ele, os usuários são importados como perfis e definem uma nova senha no primeiro login.

Referência da API

Cada tenant expõe um servidor OIDC em conformidade com os padrões em https://{slug}.authagonal.io. Todos os endpoints seguem as especificações OAuth 2.0 e OpenID Connect. Esta referência cobre todos os endpoints com os quais sua aplicação pode precisar interagir.

Fluxo de Authorization Code com PKCE

OIDC Discovery & JWKS

O documento de discovery permite que bibliotecas de cliente OIDC se configurem automaticamente. Nenhuma autenticação é necessária para nenhum dos endpoints.

GET /.well-known/openid-configuration

Retorna o documento de Configuração do Provedor OpenID. A resposta inclui todos os metadados que seu cliente precisa para interagir com este tenant.

GET /.well-known/openid-configuration/jwks

Retorna o JSON Web Key Set usado para verificar assinaturas de tokens. A resposta contém um array keys com chaves públicas RSA, cada uma incluindo os campos kty, use, kid, alg, n e e.

curl https://acme.authagonal.io/.well-known/openid-configuration

Endpoint de Autorização

GET /connect/authorize

Inicia um fluxo de authorization code. O usuário deve ter uma sessão ativa ou será redirecionado para a página de login. Em caso de sucesso, o usuário é redirecionado de volta para sua aplicação com um authorization code.

Resposta de sucesso: Redirecionamento 302 para redirect_uri com parâmetros de query code e state.

Resposta de erro: Redirecionamento 302 com parâmetros de query error, error_description e state.

Pushed Authorization Requests (PAR)

RFC 9126. Em vez de colocar todos os parâmetros de autorização na URL, seu cliente os envia por POST para /connect/par com autenticação de cliente normal e recebe de volta uma request_uri opaca e de curta duração. O navegador então visita /connect/authorize?client_id=...&request_uri=... — nada mais entra no histórico do navegador, logs do servidor ou cabeçalhos Referer, e o servidor já verificou a integridade dos parâmetros sob autenticação do cliente.

POST /connect/par

A autenticação do cliente é a mesma de /connect/token: HTTP Basic com client_id/client_secret ou credenciais codificadas no formulário. Clientes públicos publicam sem segredo. O corpo carrega os mesmos parâmetros que você enviaria normalmente para /connect/authorize; o próprio request_uri é rejeitado (encadear um PAR é proibido pelo §2.1 da especificação). Retorna 201 Created.

Resposta

Na chamada seguinte GET /connect/authorize?client_id=…&request_uri=…, todos os outros parâmetros são puxados do payload enviado e quaisquer parâmetros de query extras são ignorados. O client_id na chamada de autorização deve corresponder ao cliente que enviou a solicitação. Uma vez consumida (ou após expires_in), a request_uri é removida do armazenamento.

# 1. Push parameters (server returns request_uri + expires_in)
curl -X POST https://acme.authagonal.io/connect/par \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "response_type=code" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "scope=openid profile email" \
  -d "state=$(openssl rand -hex 16)" \
  -d "code_challenge=YOUR_CODE_CHALLENGE" \
  -d "code_challenge_method=S256"

# 2. Send the user to /authorize with only client_id + request_uri
# https://acme.authagonal.io/connect/authorize?client_id=my-app&request_uri=urn:ietf:params:oauth:request_uri:abc123...

Endpoint de Token

POST /connect/token

Troca credenciais por tokens. As requisições devem usar Content-Type: application/x-www-form-urlencoded. A autenticação do cliente pode ser fornecida via HTTP Basic auth (Authorization: Basic base64(client_id:client_secret)) ou como parâmetros no corpo do formulário (client_id + client_secret).

Concessão de Authorization Code

Concessão de Refresh Token

Concessão de Client Credentials

Concessão de Device Code

Resposta do token:

curl -X POST https://acme.authagonal.io/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "client_id=my-app" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

Endpoint UserInfo

GET /connect/userinfo

Retorna claims sobre o usuário autenticado. Requer um access token válido com o escopo openid.

curl https://acme.authagonal.io/connect/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Token Introspection (RFC 7662)

POST /connect/introspect

Valida um token e retorna seus metadados. Requer credenciais de cliente (Basic auth ou parâmetros no corpo do formulário).

Resposta de token ativo:

Resposta de token inativo: { "active": false }

curl -X POST https://acme.authagonal.io/connect/introspect \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_OR_REFRESH_TOKEN"

Revogação de Token (RFC 7009)

POST /connect/revocation

Revoga um token emitido anteriormente. Requer credenciais de cliente.

O endpoint sempre retorna 200 OK, mesmo para tokens inválidos ou já revogados, conforme a especificação RFC 7009.

Autorização de Dispositivo (RFC 8628)

POST /connect/deviceauthorization

Inicia o fluxo de autorização de dispositivo para dispositivos com restrição de entrada (CLIs, smart TVs, dispositivos IoT). O dispositivo exibe um código para o usuário, que então aprova a requisição em um dispositivo separado com navegador.

Resposta:

Fluxo de aprovação: O usuário visita a verification_uri, insere o user_code e aprova a requisição. Enquanto isso, o dispositivo faz polling no endpoint de token com o device_code.

Códigos de erro de polling:

curl -X POST https://acme.authagonal.io/connect/deviceauthorization \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-cli" \
  -d "scope=openid profile email"

Encerrar Sessão / Logout

GET POST /connect/endsession

Encerra a sessão do usuário atual, aciona o logout por back-channel para todos os clientes com um BackChannelLogoutUri registrado e revoga todas as concessões.

Se um post_logout_redirect_uri válido for fornecido e corresponder a uma URI registrada, o usuário recebe um redirecionamento 302. Caso contrário, uma resposta JSON confirma que a sessão foi encerrada.

Referência da API SCIM 2.0

Authagonal suporta o protocolo SCIM 2.0 para provisionamento automatizado de usuários e grupos. Provedores de identidade como Okta, Azure AD e OneLogin podem usar esta API para manter seu tenant Authagonal sincronizado com seu diretório corporativo.

URL Base: https://{slug}.authagonal.io/scim/v2

Autenticação: Todas as requisições requerem um token Bearer. Gere um token SCIM no portal em Configurações > Provisionamento SCIM.

Cabeçalhos comuns:

Endpoints de listagem suportam paginação via parâmetros de query startIndex (base 1) e count (máx. 200), e filtragem via o parâmetro filter (ex: userName eq "user@example.com").

Usuários

GET /scim/v2/Users — Lista usuários com paginação e filtragem opcionais.

GET /scim/v2/Users/{id} — Obtém um único usuário pelo ID de usuário Authagonal.

POST /scim/v2/Users — Cria um novo usuário. Retorna 201 Created.

PUT /scim/v2/Users/{id} — Substituição completa de um recurso de usuário. Todos os campos devem ser fornecidos.

PATCH /scim/v2/Users/{id} — Atualização parcial usando SCIM PatchOp.

DELETE /scim/v2/Users/{id} — Exclui suavemente o usuário (desativa a conta e revoga todos os tokens). Retorna 204 No Content.

curl -X POST https://acme.authagonal.io/scim/v2/Users \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "jane@acme.com",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "displayName": "Jane Smith",
    "active": true,
    "externalId": "ext-12345"
  }'

Grupos

GET /scim/v2/Groups — Lista todos os grupos com paginação e filtragem opcionais.

GET /scim/v2/Groups/{id} — Obtém um único grupo por ID, incluindo sua lista de membros.

POST /scim/v2/Groups — Cria um novo grupo. Retorna 201 Created.

PUT /scim/v2/Groups/{id} — Substituição completa de um recurso de grupo (incluindo sua lista de membros).

PATCH /scim/v2/Groups/{id} — Atualização parcial para adicionar ou remover membros do grupo.

DELETE /scim/v2/Groups/{id} — Exclui permanentemente o grupo. Retorna 204 No Content.

curl -X PATCH https://acme.authagonal.io/scim/v2/Groups/GROUP_ID \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "add",
        "path": "members",
        "value": [
          { "value": "USER_ID_1" },
          { "value": "USER_ID_2" }
        ]
      }
    ]
  }'

Portal API (automação)

A Portal API permite que o seu próprio backend automatize tudo o que pode fazer no portal — gerir usuários, clients, grupos, funções, escopos, conexões SSO e configurações — usando uma credencial máquina-a-máquina. É a mesma API que a interface do portal chama.

URL Base: https://portal-api.<your-domain>/api/v1. As requisições autenticam-se com um token de acesso Bearer; o tenant é obtido a partir do token, não do URL.

Criando uma credencial de API

No portal, abra Clients → Create API credential, escolha um nível de acesso e dê-lhe um nome. O Authagonal gera um client OAuth client_credentials configurado para a Portal API e retorna um client ID e um secret.

Níveis de acesso

Obtendo um token

Troque a credencial por um token de acesso no endpoint de token do seu tenant de administração — https://<your-tenant>.<your-domain>/connect/token — e depois envie o token como cabeçalho Bearer para a Portal API. Os tokens são válidos por uma hora.

# 1. Exchange the credential for an access token (your tenant's token endpoint)
curl -X POST https://acme.authagonal.io/connect/token \
  -d grant_type=client_credentials \
  -d client_id=api-3f2a... \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope=tenant:admin

# Response: { "access_token": "ey...", "token_type": "Bearer", "expires_in": 3600 }

# 2. Call the Portal API with the access token
curl https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoints

Todos os caminhos são relativos à URL base e exigem um token de acesso Bearer. O escopo ao lado de cada grupo é o nível de acesso mínimo que a credencial precisa. Os endpoints de listagem aceitam os parâmetros de consulta startIndex e count.

GET/api/v1/clients— Listar clientes OAuth.

GET/api/v1/clients/{id}— Obter um único cliente por ID.

POST/api/v1/clients— Criar um cliente. Retorna o ID do cliente e, para clientes confidenciais, um segredo de uso único.

PUT/api/v1/clients/{id}— Atualizar um cliente (URIs de redirecionamento, tipos de concessão, tempos de vida de token, requisitos PKCE/PAR).

DELETE/api/v1/clients/{id}— Excluir um cliente.

POST/api/v1/clients/api-credential— Gerar uma credencial de API do Portal máquina a máquina.

GET/api/v1/users— Listar usuários. Suporta startIndex, count e search (prefixo de e-mail / nome).

GET/api/v1/users/count— Número total de usuários do inquilino.

GET/api/v1/users/stats/mfa— Estatísticas de inscrição em MFA.

GET/api/v1/users/{id}— Obter um único usuário.

POST/api/v1/users— Criar um usuário com e-mail e senha.

PUT/api/v1/users/{id}— Atualizar um usuário (perfil, e-mail, estado ativado/bloqueado).

DELETE/api/v1/users/{id}— Excluir um usuário.

GET/api/v1/users/{id}/mfa— Get a user's enrolled MFA methods.

DELETE/api/v1/users/{id}/mfa— Reset a user's MFA enrollment.

GET/api/v1/roles— Listar funções.

POST/api/v1/roles— Criar uma função.

DELETE/api/v1/roles/{id}— Excluir uma função.

POST/api/v1/roles/assign— Atribuir uma função a um usuário.

POST/api/v1/roles/unassign— Remover uma função de um usuário.

GET/api/v1/groups— Listar grupos.

GET/api/v1/groups/{id}— Obter um grupo com seus membros.

POST/api/v1/groups— Criar um grupo.

POST/api/v1/groups/{id}/members— Adicionar membros a um grupo.

DELETE/api/v1/groups/{groupId}/members/{userId}— Remover um membro de um grupo.

DELETE/api/v1/groups/{id}— Excluir um grupo.

GET/api/v1/group-role-mappings— Listar os mapeamentos de grupo para função (funções concedidas na emissão do token conforme a associação ao grupo).

GET/api/v1/scopes— Listar escopos de API.

POST/api/v1/scopes— Criar um escopo.

DELETE/api/v1/scopes/{name}— Excluir um escopo.

GET/api/v1/saml/connections— Listar conexões SAML.

POST/api/v1/saml/connections— Criar uma conexão SAML.

DELETE/api/v1/saml/connections/{id}— Excluir uma conexão SAML.

GET/api/v1/oidc/connections— Listar conexões OIDC.

POST/api/v1/oidc/connections— Criar uma conexão OIDC.

DELETE/api/v1/oidc/connections/{id}— Excluir uma conexão OIDC.

GET/api/v1/sso/domains— Listar os domínios roteados para conexões SSO (descoberta de home-realm).

GET/api/v1/branding— Obter a personalização do inquilino (cores, logotipo, idiomas suportados).

PUT/api/v1/branding— Atualizar a personalização do inquilino.

GET/api/v1/settings— Obter as configurações do inquilino (webhooks, cadastro público, política de tokens).

PUT/api/v1/settings— Atualizar as configurações do inquilino.

POST/api/v1/settings/webhook-secret/regenerate— Rotacionar o segredo de assinatura do webhook.

POST/api/v1/settings/test-email— Enviar um e-mail de teste com a configuração de e-mail atual.

GET/api/v1/custom-domains— Listar domínios de login personalizados e seu status de verificação.

POST/api/v1/custom-domains— Adicionar um domínio personalizado.

POST/api/v1/custom-domains/{domain}/verify— Disparar a verificação de DNS de um domínio personalizado.

DELETE/api/v1/custom-domains/{domain}— Remover um domínio personalizado.

GET/api/v1/email/domains— Listar domínios de e-mail do remetente.

GET/api/v1/audit— Consultar o registro de auditoria do inquilino.

Exemplo: criar um usuário

curl -X POST https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@acme.com",
    "password": "S3cure-temp-passw0rd",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }'

# 200 OK
# { "userId": "8f3a...", "email": "ada@acme.com" }

Fluxos de Autenticação

Os fluxos de autenticação cobrem como os usuários finais interagem com seu tenant Authagonal — fazendo login, se cadastrando, redefinindo senhas e configurando MFA. Esses endpoints são usados pela página de login hospedada e podem ser chamados diretamente se você estiver construindo uma UI de login personalizada.

Login

POST /api/auth/login

Autentica um usuário com e-mail e senha. Em caso de sucesso, assina um cookie de sessão e retorna o perfil do usuário. Se o MFA estiver configurado, a resposta indica que um segundo fator é necessário antes que a sessão seja totalmente estabelecida.

Corpo da requisição:

{
  "email": "user@example.com",
  "password": "correct-horse-battery-staple"
}

Resposta de sucesso:

Resposta de MFA obrigatório: Quando o usuário tem MFA inscrito, a resposta inclui mfaRequired: true junto com um challengeId e um array methods listando os métodos MFA disponíveis.

Resposta de configuração de MFA obrigatória: Quando o tenant exige MFA mas o usuário ainda não se inscreveu, a resposta inclui mfaSetupRequired: true com um setupToken para o fluxo de inscrição.

Respostas de erro:

Verificação de SSO: Se o domínio de e-mail do usuário tem uma conexão SSO configurada, o endpoint de login retorna sso_required com um redirectUrl. O cliente deve redirecionar o usuário para o provedor SSO.

Bloqueio de conta: Após maxFailedAttempts tentativas de login consecutivas com falha, a conta é bloqueada por lockoutDurationMinutes. Ambos os valores são configuráveis nas configurações do tenant.

Cadastro

POST /api/auth/register

Cria uma nova conta de usuário. Um e-mail de verificação é enviado automaticamente — o usuário deve verificar seu e-mail antes de poder fazer login.

Corpo da requisição:

{
  "email": "newuser@example.com",
  "password": "a-strong-password-here",
  "firstName": "Jane",
  "lastName": "Smith"
}

Sucesso: 201 Created com o userId da nova conta.

Respostas de erro:

Redefinição de Senha

POST /api/auth/forgot-password

Solicita um e-mail de redefinição de senha. O endpoint sempre retorna uma resposta de sucesso independentemente de o e-mail existir, para prevenir enumeração de e-mails.

{
  "email": "user@example.com"
}

POST /api/auth/reset-password

Redefine a senha do usuário usando o token do link de e-mail.

{
  "token": "RESET_TOKEN_FROM_EMAIL",
  "newPassword": "new-strong-password"
}

Efeitos colaterais de uma redefinição de senha bem-sucedida:

• O contador de tentativas de login com falha é zerado
• Todos os refresh tokens existentes são revogados
• Um novo security stamp é gerado (invalidando todas as sessões existentes)

Configuração e Verificação de MFA

Authagonal suporta três métodos de MFA: TOTP (aplicativos autenticadores), WebAuthn (chaves de segurança e biometria) e códigos de recuperação de uso único.

Configuração TOTP

POST /api/auth/mfa/totp/setup — Retorna uma URI de dados de QR code e uma chave de entrada manual. O usuário escaneia o QR code com seu aplicativo autenticador (Google Authenticator, Authy, 1Password, etc.) e confirma a inscrição.

POST /api/auth/mfa/totp/confirm — Confirma a inscrição TOTP validando um código de 6 dígitos do aplicativo autenticador.

{
  "code": "123456"
}

Configuração WebAuthn

POST /api/auth/mfa/webauthn/setup — Retorna opções de criação de credencial para a API WebAuthn. O navegador chama navigator.credentials.create() com essas opções.

POST /api/auth/mfa/webauthn/confirm — Confirma a inscrição WebAuthn enviando a resposta de attestation do navegador.

Códigos de Recuperação

POST /api/auth/mfa/recovery/generate — Gera 10 códigos de recuperação de uso único com 8 caracteres. Cada código pode ser usado exatamente uma vez para ignorar o MFA.

Verificação de MFA

POST /api/auth/mfa/verify — Completa o desafio de MFA após um login com senha bem-sucedido.

Status do MFA

GET /api/auth/mfa/status — Retorna os métodos de MFA atualmente inscritos do usuário.

Fluxo de Login SSO

Authagonal suporta conexões SSO baseadas em SAML 2.0 e OIDC. O roteamento baseado em domínio detecta automaticamente qual provedor SSO usar com base no endereço de e-mail do usuário.

Verificação de SSO

GET /api/auth/sso-check?email=user@acme.com

Fluxo SAML

O usuário é redirecionado para GET /saml/{connectionId}/login que envia uma SAML AuthnRequest para o provedor de identidade. O IdP autentica o usuário e envia uma resposta SAML de volta para o endpoint Assertion Consumer Service (ACS). Authagonal valida a assertion, cria ou atualiza o usuário e assina um cookie de sessão.

Os metadados SAML para configurar seu IdP estão disponíveis em GET /saml/{connectionId}/metadata.

Fluxo OIDC

O usuário é redirecionado para GET /oidc/{connectionId}/login que redireciona para o provedor de identidade upstream com PKCE. Após o usuário se autenticar, o callback em /oidc/callback troca o authorization code, valida o token de ID e cria ou atualiza o usuário.

Provisionamento JIT: Tanto os fluxos SAML quanto OIDC suportam provisionamento just-in-time. Se o usuário ainda não existir no tenant, ele é criado automaticamente a partir das claims do provedor de identidade. Se já existir, seus atributos de perfil são atualizados para corresponder aos valores mais recentes do provedor.

Crie uma interface de login personalizada

Substitua as telas de login, registro, redefinição de senha e MFA hospedadas pela Authagonal pela sua própria interface, enquanto a Authagonal continua cuidando da autenticação, MFA, SSO, sessões e emissão de tokens. Dois caminhos: use nossa biblioteca de componentes React ou chame a API de autenticação diretamente de qualquer framework. É opcional — primeiro ative Custom login UI nas configurações do tenant.

Pré-requisito: um domínio personalizado no seu domínio raiz

A sessão de login é um cookie first-party, então sua interface e o servidor de autenticação da Authagonal devem compartilhar um domínio registrável. Aponte um domínio de autenticação personalizado para a Authagonal no mesmo domínio raiz em que seu aplicativo é executado — por exemplo, autenticação em login.acme.com, aplicativo em app.acme.com. A configuração Custom login UI permanece desativada até que exista um domínio personalizado ativo.

Adicione também a origem da sua interface (por exemplo, https://app.acme.com) às Allowed CORS origins do seu cliente OAuth — a mesma lista que você define para a troca de tokens.

React: @authagonal/login

npm i @authagonal/login entrega a lógica de autenticação e a interface em um único pacote — o mesmo sobre o qual o login hospedado da Authagonal é construído. Escolha sua altitude:

• Aplicativo completo — adicione App e personalize o tema via branding.
• Componha páginas — use LoginPage, MfaChallengePage, ResetPasswordPage… dentro do seu próprio layout.
• Primitivos + lógica — crie suas próprias telas com AuthLayout/Button/Input e o cliente da API (login, mfaVerify, forgotPassword, …).

import { AuthLayout, Input, Button, login, ApiRequestError } from '@authagonal/login';

function MyLogin() {
  async function onSubmit(email: string, password: string) {
    try {
      const res = await login({ email, password });        // POST /login (sets the session cookie)
      if (res.mfaRequired) {/* render your MFA step → mfaVerify(...) */}
      else window.location.href = res.returnUrl;            // hand off to /connect/authorize
    } catch (e) {
      if (e instanceof ApiRequestError) {/* show e.message */}
    }
  }
  return <AuthLayout>{/* your own markup + <Input/> <Button/> */}</AuthLayout>;
}

Qualquer framework: chame a API de autenticação

Não usa React? Chame os endpoints do fluxo de autenticação diretamente (em /api/auth) e, em seguida, repasse para o fluxo OIDC padrão /connect/authorize. Envie credentials: 'include' para que o cookie de sessão seja armazenado.

# 1. Authenticate (browser fetch — credentials:'include' so the session cookie is stored)
curl -i -X POST https://login.acme.com/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.acme.com" \
  --data '{"email":"jane@acme.com","password":"..."}'
# (handle {"mfaRequired":true} → POST /api/auth/mfa/verify, then continue)

# 2. Hand off to the OAuth flow — top-level navigation to the authorize endpoint with PKCE:
# https://login.acme.com/connect/authorize?client_id=my-app&redirect_uri=...&response_type=code
#   &scope=openid%20profile%20email&code_challenge=...&code_challenge_method=S256
# The session cookie (same-site) authenticates the user; you get back a code → exchange at /connect/token.

Planos e Limites

Authagonal oferece quatro níveis de plano. Todos os planos incluem todos os recursos — a única diferença é o limite de Usuários Ativos Mensais (MAU) e o preço de excedente.

Níveis de Plano

Usuários Ativos Mensais (MAU)

Um Usuário Ativo Mensal é qualquer usuário único que se autentica com sucesso pelo menos uma vez durante um mês de faturamento. Usuários provisionados via SCIM que não fizeram login não contam para o total de MAU.

Excedente — Se seu plano suporta excedente, usuários além do limite de MAU são cobrados pela taxa por usuário mostrada na tabela de planos acima. Você pode definir um limite de excedente para limitar seu gasto máximo no período de faturamento.

Aplicação — Se seu plano não suporta excedente (Starter), usuários além do limite de MAU não podem fazer login até o próximo período de faturamento ou até você fazer upgrade para um plano que suporte excedente.