Realms
A Realm is an isolated authentication domain in VoxKey. Each realm operates independently with its own set of users, applications, providers, cryptographic keys, and configuration.
What's inside a Realm
| Component | Description |
|---|---|
| Users | User accounts scoped to this realm |
| Applications | OAuth2 clients (web apps, SPAs, M2M services) |
| Providers | Authentication methods (Google, GitHub, password, etc.) |
| Roles & Scopes | RBAC permissions for API access |
| Keys | Per-realm RSA keys for JWT signing and encryption |
| Sessions | Active user sessions tracked via rid cookie |
| Branding | Custom login page appearance per realm |
How it works
Every OAuth2 endpoint is scoped to a realm via its UUID:
/oauth2/{realmUUID}/code
/oauth2/{realmUUID}/token
/oauth2/{realmUUID}/.well-known/openid-configuration
Users in one realm are completely isolated from users in another. The same email address can exist in multiple realms as separate accounts.
Use cases
Multi-tenant SaaS -- Give each customer their own realm with separate user pools, branding, and auth providers.
Environment separation -- Use different realms for development, staging, and production with different configurations.
Multiple products -- Run separate authentication domains for different products under a single VoxKey instance.
White-label auth -- Each realm can have custom branding (logo, colors, text) on the login page.
Creating a Realm
- Open the Admin Panel at
/admin - Navigate to Realms and click Create
- Enter a name for the realm
- VoxKey auto-generates a UUID, RSA keypair, and encryption key
- A built-in Management API resource is created automatically with all CRUD scopes
External Database
Each realm can optionally use a separate database for user storage. Configure db_host, db_name, db_username, and db_password in realm settings to point to an external MariaDB/MySQL instance.
Realm Settings
Realms have granular configuration sections:
- Auth settings -- sign-up/sign-in behavior, session lifetimes
- MFA settings -- TOTP, WebAuthn enforcement policies
- Security settings -- rate limits, CAPTCHA
- Branding settings -- logo, colors, custom CSS
- Profile settings -- required user fields, email verification
- Notification settings -- email templates and providers