Role-Permission Matrix
Last Updated: 2026-04-03 Source of truth: Route middleware configuration in
routes/api.php,routes/admin.php,routes/billing.php
Authentication Guards
| Guard | Model | Token Prefix | Usage |
|---|---|---|---|
sanctum (web) | User | validonx_ | SPA tenant users — onboarding, billing portal, account |
admin | Admin | validonx_ | Admin panel — tenant management, billing admin, audit |
| API Key | ApiKey | VXS- / VXP- / VXE- | Integration API — license validation, activations |
Route Groups & Middleware
Public (no auth)
| Route | Middleware | Purpose |
|---|---|---|
GET /api/v1/plans | — | List available plans |
POST /api/v1/auth/register | throttle:6,1 | User registration |
POST /api/v1/auth/forgot-password | throttle:6,1 | Password reset request |
POST /api/v1/auth/reset-password | throttle:6,1 | Password reset |
POST /api/v1/marketing/* | throttle:10,1 | Newsletter subscribe/unsubscribe |
GET /health | — | Basic health check |
GET /metrics | — | Prometheus metrics |
POST /webhooks/stripe | VerifyStripeWebhookSignature | Stripe webhooks |
Tenant User (auth:sanctum)
| Route | Additional Middleware | Purpose |
|---|---|---|
POST /api/v1/auth/email/verify | — | Verify email |
POST /api/v1/auth/email/resend | throttle:3,1 | Resend verification |
POST /api/v1/onboarding/* | VerifyEmailMiddleware | Checkout + provisioning |
GET/POST /api/v1/account/* | — | GDPR data export/deletion |
GET/PUT /v1/billing/* | ResolveTenantFromUser | Billing portal |
Admin (AuthenticateAdmin)
| Route | Additional Middleware | Purpose |
|---|---|---|
GET/POST/PATCH /api/v1/admin/tenants/* | — | Tenant CRUD |
* /api/v1/admin/tenants/{tenantId}/* | ResolveTenantFromPath | Tenant-scoped admin actions — see below |
GET /api/v1/admin/metrics | — | Platform metrics |
GET /api/v1/admin/audit | — | Audit log |
GET /api/v1/admin/rate-limits/* | — | Rate limit dashboard |
GET/POST/PUT/DELETE /api/v1/admin/catalog/* | — | Product catalog CRUD |
GET/POST/PUT/DELETE /api/v1/admin/feature-flags/* | — | Feature flags CRUD |
GET/POST /api/v1/admin/subscriptions/* | — | Subscription management |
GET/POST /api/v1/admin/invoices/* | — | Invoice management |
* /api/v1/admin/billing/* | AuthorizeBillingRole | Billing admin (role-gated) |
Admin Tenant-Scoped (AuthenticateAdmin + ResolveTenantFromPath)
Mirrors every route under /api/v1/tenant/* so admins can manage any tenant's resources without SSH + tinker. ResolveTenantFromPath reads {tenantId} from the URL, validates the tenant is active, connects the tenant DB, and binds the Tenant on the request — identical downstream contract to ResolveTenantFromUser. The same Tenant\* controllers serve both flows.
| Route | Purpose |
|---|---|
GET /api/v1/admin/tenants/{tenantId}/products | List tenant products |
GET /api/v1/admin/tenants/{tenantId}/products/{id} | Read tenant product |
GET/POST/PUT/DELETE /api/v1/admin/tenants/{tenantId}/licenses | Tenant license CRUD |
GET /api/v1/admin/tenants/{tenantId}/activations | Tenant activations |
GET /api/v1/admin/tenants/{tenantId}/entitlements | Tenant entitlements |
GET/POST/DELETE /api/v1/admin/tenants/{tenantId}/api-keys | Tenant API keys |
GET/PUT /api/v1/admin/tenants/{tenantId}/settings | Tenant settings |
GET /api/v1/admin/tenants/{tenantId}/audit-logs | Tenant audit log |
GET/POST/PUT/DELETE /api/v1/admin/tenants/{tenantId}/webhooks | Webhook endpoint CRUD |
GET /api/v1/admin/tenants/{tenantId}/webhook-deliveries | Webhook delivery history |
GET/POST /api/v1/admin/tenants/{tenantId}/notifications | Tenant notifications |
GET /api/v1/admin/tenants/{tenantId}/dev-tools/snapshot | Developer tools snapshot |
Audit attribution on this route group: every write routed through AuditService::log() records actor_type='admin', actor_id=<admin.id>, and appends _BY_ADMIN to the final segment of the event code (e.g. LICENSE.CREATED_BY_ADMIN, API_KEY.CREATED_BY_ADMIN). Tenant flow (/api/v1/tenant/*) continues to record actor_type='user' and plain event codes.
Billing Role Authorization (AuthorizeBillingRole)
| HTTP Method | Required Level | Allowed Roles |
|---|---|---|
| GET | read | billing_readonly, billing_admin, super_admin |
| POST, PUT, PATCH, DELETE | write | billing_admin, super_admin |
Integration API (ResolveTenantFromApiKey + EnforceRateLimit)
| Route | Auth | Purpose |
|---|---|---|
POST /api/v1/integration/* | X-API-Key header | License/activation/entitlement/usage |
Audit Coverage
All admin authentication events (login, logout, failed attempts, lockouts) are logged via AuditService. All billing authorization failures are logged via BillingAuthorizationLogService. The X-Request-ID header provides end-to-end traceability.