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.
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().
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.
# 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#
'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 }
}
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.
| Method | Endpoint | Description |
|---|---|---|
POST | /v1/auth/register | Create an account with email and password |
POST | /v1/auth/login | Sign in with a password |
GET | /v1/auth/oauth/{provider}/start | Start an OAuth flow (PKCE) |
POST | /v1/auth/magic-link | Send a magic link |
POST | /v1/auth/email-otp/send | Send a one-time code by email |
POST | /v1/auth/mfa/setup | Enroll a TOTP factor |
POST | /v1/auth/refresh | Refresh the token pair |
GET | /v1/auth/me | Return the current user |
GET | /v1/auth/sessions | List active sessions |
DELETE | /v1/auth/sessions/{session_id} | Revoke a session |
POST | /v1/auth/logout | End the current session |