Skip to content
Aurabase Logo
aurabase

Authentication

OAuth with 15 providers, TOTP MFA, magic links, one-time codes by email and SMS, and role-based access control, from a single SDK.

Explanation7 min readLevel intermediateRevised on Apr 15, 2026

What aura-auth does#

The aura-auth service issues and validates JWTs for users in a project. The signature is ES256 by default, with a project-derived secret; RS256 (and exposing a JWKS) is only used if an RSA key is configured — this is an opt-in, not the default behavior. It manages the complete lifecycle: registration, email verification, MFA, refresh token rotation, server-side revocation.

Each token embeds sub, project_id, role (anon or authenticated), email, and an app_metadata object that carries your server-side claims (tenant, roles). The gateway injects these claims into Postgres connections via request.jwt.claims, making RLS policies directly accessible to auth.uid(), auth.role(), auth.tenant().

Info

User tables live in project_{uuid}_auth: users, oauth_accounts, refresh_tokens, mfa_factors, sessions, auth_audit_log.

Three actors, three responsibilities#

The client signs a challenge, the service queries the database, the gateway validates on each subsequent request.

sign-in flowtext
# 1. Client → aura-auth: credentials
POST /v1/auth/login  { email, password }

# 2. aura-auth: Argon2id verify + MFA if required (status remains 200)
if password OK && mfa_required  →  data = { mfa_required: true, mfa_token }
else                            →  data = { access_token, refresh_token, user, ... }

# 3. Subsequent requests go through gateway
apikey: <anon_key>   +   Authorization: Bearer <jwt>
gateway vérifie le JWT  →  claims injectés → Postgres RLS

Eight mechanisms ready#

  • Email + password. Argon2id, optional email verification, secure rotation.
  • OAuth 2.1 · PKCE. 15 providers — Google, GitHub, Apple, Microsoft, Discord, Twitter, Facebook, Bitbucket, Figma, Notion, Spotify, Twitch, Zoom, Kakao, Snapchat.
  • MFA TOTP. Authy, 1Password, Google Authenticator. Fallback SMS.
  • Magic links & OTP. Email without password, i18n templates, rate-limit by address.
  • Granular RBAC. Roles, permissions, org hierarchies. Self-generated RLS policies.
  • Session binding. Device fingerprint, IP check, rotation refresh tokens.

Four streams, one SDK#

app/actions/auth.tstypescript
'use server'
import { aura } from '@/lib/aurabase'

export async function signUp(email: string, password: string) {
  const { data, error } = await aura.auth.signUp({
    email,
    password,
    options: { emailRedirectTo: '/auth/callback' },
  })
  if (error) return { error }
  return { user: data.user }
}
Server-side session

In Next.js App Router, always use the createServerClient helper from @aurabase/aurabase-js/ssr in server actions and route handlers. The cookie refresh token is httpOnly and should never be read by client JS.

If you are not using the SDK#

All flows are also exposed in raw REST, with the same server-side validations. See /docs/api-rest for the complete list.

MethodEndpointDescription
POST/v1/auth/registerCreate an account with email and password
POST/v1/auth/loginSign in with a password
GET/v1/auth/oauth/{provider}/startStart an OAuth flow (PKCE)
POST/v1/auth/magic-linkSend a magic link
POST/v1/auth/email-otp/sendSend a one-time code by email
POST/v1/auth/mfa/setupEnroll a TOTP factor
POST/v1/auth/refreshRefresh the token pair
GET/v1/auth/meReturn the current user
GET/v1/auth/sessionsList active sessions
DELETE/v1/auth/sessions/{session_id}Revoke a session
POST/v1/auth/logoutEnd the current session

To go further#