Core Concepts

Sectors

A sector is an isolated namespace for users, security settings, OAuth providers, and allowed origins.

Your organization has a tenant root sector (the default sector you log into in the dashboard). From there you create sub-sectors. Put one sub-sector per application you host. The tenant root can authenticate an app, but mixing products in the root mixes users, CORS, OAuth clients, and API keys.

Tenant root admins can manage every sector in the organization. Sub-sector admins only manage that sector. End-user login always targets a single sector ID — use the sub-sector ID in the login widget. See Managing Sectors.

Key sector properties:

• Sector ID — a UUID you pass to the login widget and your backend
• Slug — URL identifier for dashboard login (/login/{slug}); set at create and immutable
• Domain — the primary domain for the app that uses this sector (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-...",
    "tid": "2c27e84b-...",
    "isAdmin": false,
    "exp": "1717000000",
    "iat": "1716996400"
  }
}

sectorID is the sector the user authenticated against (use this to match the login widget). tid identifies the organization and is present on hosted multi-tenant tokens.

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.