Aura Logo
aurabasedocumentos
documentos›Guias›Authenticate users (SDK)

Autenticar usuários com o JavaScript SDK

Os fluxos diários de aura.auth, com o comportamento de cada chamada observado em uma pilha em execução.

11 min lido·Nível intermediário·Revisado em 12 de out. de 2026
Este texto em inglês foi gerado automaticamente a partir do original em francês e ainda não foi revisado.
A fonte em inglês mudou desde esta tradução. Algumas informações podem estar desatualizadas.
Esta página foi traduzida automaticamente. A versão em inglês é oficial.
#
Noções básicas

1. Cadastre-se e faça login

auth.tstypescript
import { createClient, isMfaChallenge } from '@aurabase/aurabase-js'

const aura = createClient(process.env.AURA_URL!, process.env.AURA_ANON_KEY!)

// Crie uma conta
const { data, error } = await aura.auth.signUp({ email: 'ada@example.com', password: 'a-long-passphrase' })

// Faça login
const login = await aura.auth.signInWithPassword({ email: 'ada@example.com', password: 'a-long-passphrase' })
if (login.error) return showError(login.error.message)
if (login.data && isMfaChallenge(login.data)) return askForTotpCode(login.data.mfa_token)
// caso contrário, existe agora uma sessão

Ambas as chamadas retornam a mesma forma. Em caso de sucesso, data mantém access_token, refresh_token, expires_in (900 segundos) e user, e o cliente armazena a sessão para você. A próxima solicitação já está autenticada.

O que signUp faz depende das configurações do seu projeto. Em nosso projeto de teste, o usuário entrou imediatamente com email_verified: false, e um projeto pode exigir confirmação primeiro.

Falhas que você deve tratar, conforme observado:

LigarErro
Senha errada401, code: 'invalid_credentials', "Identificadores inválidos"
Link ou código inválido ou expirado401, code: 'invalid_otp'
Login anônimo quando o projeto não permite isso403, FORBIDDEN

signInAnonymously() cria um usuário sem endereço de e-mail, mas em um novo projeto ele é desabilitado e retorna 403 até que você habilite nas configurações de autenticação do projeto.

#
Estado

2. A sessão e seus eventos

session.tstypescript
const { data: { session } } = await aura.auth.getSession() // nenhuma chamada de rede: lê a loja
const { data: user } = await aura.auth.getUser()           // pergunta ao servidor

const { data: { subscription } } = aura.auth.onAuthStateChange(({ event, user }) => {
  // evento: 'INITIAL_SESSION' | 'ASSINADO_IN' | 'TOKEN_REFRESHED' | 'USER_ATUALIZADO' | 'SIGNED_OUT' | 'MFA_DESAFIO'
})
subscription.unsubscribe()

Uma execução real produziu esta sequência: INITIAL_SESSION, SIGNED_IN (inscrição), SIGNED_IN (login), USER_UPDATED, TOKEN_REFRESHED, SIGNED_OUT.

  • O cliente atualiza o token de acesso antes que ele expire. Chame aura.auth.refreshSession() para forçá-lo.
  • getSession() é local e rápido: use-o para renderização. Use getUser() quando precisar da visão atual do usuário do servidor.
  • Para entregar uma sessão ao cliente de outro lugar (um cookie, um servidor), use setSession(accessToken, refreshToken). Um par inválido é recusado e a sessão anterior é mantida.
  • Para renderização no lado do servidor, consulte Next.js App Router e SSR.
#
Conta

3. Perfil e senha

profile.tstypescript
// Metadados: passe em `data`
await aura.auth.updateUser({ data: { theme: 'dark', plan: 'free' } })
// → user.user_metadata é {plan: 'free', theme: 'dark' } e getUser() retorna o mesmo

// Alterar o e-mail: o endereço NÃO muda ainda
await aura.auth.updateUser({ email: 'new@example.com' })
// Um link de confirmação vai para o novo endereço. Até ser usado, user.email mantém o valor antigo.
// Confirme com: aura.auth.verifyOtp({ type: 'email_change', token })

// Alterar a senha
await aura.auth.updatePassword('a-new-long-passphrase', 'a-long-passphrase')
Alterar a senha desconecta você

O servidor revoga todas as sessões quando a senha é alterada. updatePassword limpa a sessão local e emite SIGNED_OUT: faça login novamente com a nova senha. Em uma execução real, getSession() estava vazio logo após a chamada e o login com a nova senha funcionou.

Esqueci a senha: aura.auth.resetPasswordForEmail({ email }) envia o e-mail de redefinição. O usuário então completa com verifyOtp({ type: 'recovery', token, password }).

Excluir a conta: aura.auth.deleteUser(password) solicita a senha atual, exclui a conta e limpa a sessão local.

#
Alternativas

4. Links, códigos e OAuth

passwordless.tstypescript
// Link mágico por e-mail
await aura.auth.signInWithMagicLink({ email })
// → { mensagem: "Se este e-mail existir, uma garantia de conexão será enviada" }
// A resposta é a mesma, quer a conta exista ou não: ela não vaza contas.

// Códigos únicos
await aura.auth.signInWithEmailOtp(email)
await aura.auth.signInWithSmsOtp(phone)
await aura.auth.verifyOtp({ type: 'email', email, code })     // também: 'sms', 'magiclink', 'inscrição', 'recuperação', 'email_change'

// OAuth: o provedor é o PRIMEIRO argumento, uma string
const { data } = await aura.auth.signInWithOAuth('google', { redirectTo: 'https://app.example.com/callback' })
window.location.href = data!.url

signInWithOAuth retorna a URL para abrir; ele não navega sozinho. O provedor deve estar habilitado e configurado no projeto, caso contrário a URL inicial responde PROVIDER_NOT_CONFIGURED.

Não é o formulário supabase-js

signInWithOAuth({ provider: 'google' }) retorna o erro invalid_provider. Passe o provedor como primeiro argumento.

Após o redirecionamento de volta, o cliente lê sozinho a sessão da URL (detectSessionInUrl). Para o fluxo PKCE, passe flowType: 'pkce', mantenha o armazenamento persistente padrão e o cliente troca o código para você.

Vincule um segundo provedor a uma conta conectada com linkIdentity(provider), liste-os com listIdentities() e remova um com unlinkIdentity(identityId).

#
Segundo fator

5. Autenticação multifator

mfa.tstypescript
// 1. Inscreva-se: mostre o código QR criado a partir de otpauth_url
const { data: enrol } = await aura.auth.mfaEnroll()   // → {secreto, otpauth_url}
// 2. Confirme com o primeiro código do aplicativo autenticador: você recebe códigos de recuperação
const { data: confirm } = await aura.auth.mfaVerifySetup(codeFromApp) // → {códigos_de recuperação: [...] }

// 3. A partir de agora, o login retornará um desafio em vez de uma sessão
const login = await aura.auth.signInWithPassword({ email, password })
if (login.data && isMfaChallenge(login.data)) {
  await aura.auth.mfaVerify({ mfa_token: login.data.mfa_token, code: codeFromApp })
}

mfaUnenroll(password) desliga e regenerateRecoveryCodes(code) emite novos códigos de recuperação. Um desafio emite MFA_CHALLENGE e nenhuma sessão é armazenada até que mfaVerify seja bem-sucedido.

#
Dispositivos

6. Dispositivos e sessões

devices.tstypescript
const { data } = await aura.auth.listSessions()
// [{id, informações_do_dispositivo, endereço_ip, criado_at, expira_at, last_used_at, is_current},…]

await aura.auth.revokeSession(sessionId)   // desconectar um dispositivo
await aura.auth.revokeAllSessions()        // saia de todos os lugares, incluindo este
await aura.auth.signOut()                  // apenas este dispositivo

is_current marca a sessão que você está usando. signOut revoga o token de atualização no servidor quando houver um, limpa a sessão local e emite SIGNED_OUT.

#
Servidor

7. Administrar usuários

A administração de usuários precisa de uma chave service_role. Está disponível apenas no servidor: ler aura.authAdmin em um navegador gera um erro.

server/users.tstypescript
import { createAdminClient } from '@aurabase/aurabase-js'

const admin = createAdminClient(process.env.AURA_URL!, process.env.AURA_SERVICE_ROLE_KEY!)

const { data: users } = await admin.authAdmin.listUsers({ limit: 20, search: 'ada' })
const { data: created } = await admin.authAdmin.createUser({ email: 'bob@example.com', password: 'a-long-passphrase', email_verified: true })
await admin.authAdmin.banUser(created!.id)
await admin.authAdmin.unbanUser(created!.id)
const { data: link } = await admin.authAdmin.generateLink(created!.id, 'magic') // → {link, token}
await admin.authAdmin.deleteUser(created!.id)

const { data: stats } = await admin.authAdmin.getUserStats() // → {total, verificado, banido, mfa_enabled, new_7d }

generateLink aceita 'magic', 'recovery' ou 'invite'. O cliente administrador também gerencia as configurações de autenticação do projeto (getSettings, updateSettings), modelos de e-mail, sessões de cada usuário e o log de auditoria (getAuditLog). Cada método está listado na referência de autenticação .

Última atualização · 12 de out. de 2026