Core Concepts

Tenants#

A tenant is a developer account — you, registering to use AuthSaas for your projects. Tenant credentials are separate from end-user credentials. You log in to the tenant dashboard to manage your apps; your users log in to your app via the SDK.

Apps#

An app maps to one of your projects. Each app has:

• clientId — public identifier, safe to include in frontend code
• clientSecret — private, server-side only, hashed at rest
• allowedOrigins — CORS whitelist
• isActive — disable to immediately block all new auth for this app

Users#

Users are scoped per app — a user in App A is completely separate from a user with the same email in App B. There is no cross-app identity.

Each user record includes: id, email, emailVerified,createdAt, and their assigned roles within the app.

Tokens#

Authentication returns an access token (15-minute JWT) and a refresh token (7-day JWT). The access token is sent with every API request; the refresh token is used only to obtain a new pair. See the Security page for the full token lifecycle and rotation behaviour.

Email verification#

When a user registers, AuthSaas automatically sends a verification email containing a time-limited link. The flow works as follows:

• GET /auth/verify?token=xxx&email=xxx — validates the token and sets emailVerified: true on the user record.
• POST /auth/resend-verification — generates a fresh token and resends the email. This endpoint is rate-limited to prevent abuse.

The emailVerified field is present on the user object and is also included in the JWT payload so your application can inspect it without an extra round-trip.

RBAC#

AuthSaas ships with a fully live role-based access control system. Three default roles — owner, admin, and user — are automatically created whenever you create a new app. New users are auto-assigned the user role on registration.

Roles are per-app — they are completely isolated between your different projects. A user's admin role in App A has no effect in App B. Roles flow into the JWT roles array, which your application reads to gate features or protect routes.

Default roles#

Each app is seeded with the following role hierarchy and permission assignments:

Role    Permissions
user    read:profile, write:profile
admin   + read:users, write:users, read:audit, read:sessions
owner   + delete:users, read:roles, write:roles, delete:sessions

Permissions#

The full set of available permissions across all roles:

• read:profile
• write:profile
• read:users
• write:users
• delete:users
• read:roles
• write:roles
• read:audit
• read:sessions
• delete:sessions

Roles in JWT#

The JWT access token payload contains a roles array. Read it in your application to enforce access control without any extra API call:

// The JWT payload includes roles:
// { sub: "usr_xxx", email: "user@example.com", roles: ["admin"], appId: "app_xxx" }

// Check roles in your Next.js middleware:
import { verifyAccessToken } from '@/lib/auth';

export function middleware(req) {
  const token = req.headers.get('authorization')?.slice(7);
  const payload = verifyAccessToken(token);

  if (!payload.roles.includes('admin')) {
    return new Response('Forbidden', { status: 403 });
  }
}

Audit log#

Every auth event (register, login, logout, refresh, reuse detection) is written to an append-only audit log. Queryable per app with pagination. Useful for security reviews and compliance requirements.