Architecture
VoxKey is built around three core concepts: Realms for multi-tenancy, OAuth2/OIDC for authentication, and RBAC for authorization.
System overview
Realms (multi-tenancy)
A Realm is an isolated authentication domain. Each realm has its own:
- Users and sessions
- OAuth2 applications (clients)
- Authentication providers (social, password, passkeys)
- RSA keypair for JWT signing
- RBAC roles and API resource scopes
- Branding and configuration
All OAuth2 endpoints are realm-scoped: /oauth2/{realmUUID}/...
See Realms for details.
OAuth2/OIDC layer
VoxKey implements the following OAuth2/OIDC standards:
| Standard | Description |
|---|---|
| OAuth 2.0 Authorization Code | Primary grant type for user authentication |
| PKCE (RFC 7636) | Mandatory for public clients (SPA) |
| Client Credentials | M2M authentication |
| Refresh Token | Long-lived sessions |
| Token Introspection (RFC 7662) | Server-side token validation |
| Token Revocation (RFC 7009) | Invalidate tokens |
| OIDC Discovery | Auto-discovery of endpoints |
| JWKS | Public key distribution |
RBAC model
Authorization is managed through three entities:
- API Resources -- represent your protected APIs (identified by an audience URI)
- Scopes -- permissions belonging to an API Resource (e.g.
read:posts) - Roles -- group scopes together, assigned to users or M2M applications
When a token is issued, VoxKey resolves the user's roles, collects granted scopes, and intersects them with the requested scopes.
See Authorization for details.
Tech stack
| Component | Technology |
|---|---|
| Backend | PHP 8.4+, Laravel 11, Laravel Octane (RoadRunner) |
| Database | MariaDB 10.11 |
| Frontend | React 18, Ant Design, Vite |
| OAuth2 | league/oauth2-server |
| WebAuthn | web-auth/webauthn-lib |
| Admin | Filament 4 |