Core Concepts

Sectors

A sector is the top-level namespace for an application or tenant. Every user, security setting, OAuth provider, and allowed origin belongs to a sector.

If you are building a single-application SaaS product, you will have one sector. If you are building a multi-tenant platform, each of your customers’ tenants can be its own sector.

Key sector properties:

• Sector ID — a UUID you reference from your frontend widget and backend code
• Domain — the primary domain for your app (used in CORS and email links)
• Allowed Origins — additional CORS origins allowed to call the SpartanAuth API
• Self-Sign-Up — whether new users can register themselves, or must be invited

Profiles

A profile is a user account within a sector. Every profile belongs to exactly one sector.

A profile stores:

• sub — a stable UUID identifier for the user (use this as the foreign key in your own database)
• email / username
• Authentication credentials (hashed password, WebAuthn credentials, MFA registrations)
• Basic profile fields (first name, last name, etc.)

Note

sub is the canonical identifier. Email addresses can change; sub never changes and is never reused, even after the profile is soft-deleted.

JWTs

When a user logs in successfully, SpartanAuth issues a signed JWT (JSON Web Token). The widget stores it in localStorage under spartan-token.

The JWT payload contains a nested Claims object with these fields:

{
  "Claims": {
    "sub": "3f2a8c1d-...",
    "email": "[email protected]",
    "username": "[email protected]",
    "sectorID": "a1b2c3d4-...",
    "isAdmin": false,
    "exp": "1717000000",
    "iat": "1716996400"
  }
}

Caution

exp and iat are serialized as quoted strings, not numbers, due to protobuf’s JSON encoding of int64. Your introspection client code must handle this (see the Go example).

Never trust JWT claims for server-side authorization without verification. Always call the introspection endpoint from your backend.

Transactions

Multi-step authentication flows (MFA challenges, password reset, sign-up confirmation) are tracked via a transaction. The widget handles transactions internally — your frontend receives a transactionID alongside the final token in the spartan-login event, which you can use for audit logging if needed.

Authentication Methods

SpartanAuth supports multiple authentication methods per user, all within the same login widget:

Method	Description
Password	Standard email + password login
WebAuthn / Passkeys	FIDO2 hardware keys, device biometrics
TOTP / MFA	Time-based one-time passwords (authenticator apps)
OTP / Magic Link	One-time code sent via email or SMS
Social Login	Google, GitHub, Apple via OAuth 2.0 / OIDC

Users can enroll in multiple methods. The <spartan-account-settings> widget lets authenticated users manage their own credentials.