Overview
mgPass is an identity and loyalty platform that handles authentication, authorization, user management, and rewards across all connected applications and partner integrations.Architecture
mgPass runs entirely on edge infrastructure:Three Surfaces
| Service | Purpose | Domain |
|---|---|---|
| auth-worker | Core API — OAuth, users, RBAC, rewards | auth.mgpass.net |
| admin console | SSR admin dashboard for operators | admin.mgpass.net (staging) |
| account portal | User self-service (profile, sessions, rewards) | mgpass.net (staging) |
Infrastructure
- Edge Workers — Serverless compute at the edge
- Relational Database — SQLite-compatible database for all persistent data
- Key-Value Store — Sessions, caching, and feature flags
- Object Storage — User avatars and uploaded assets
Core Concepts
Users
Every person in the system has a user record with a unique ID, profile data (name, email, phone, avatar), and authentication credentials. Users can sign in with email/password or linked social accounts.Applications (OAuth Clients)
External applications register as OAuth clients to authenticate users. Each app has a client ID, secret, redirect URIs, and configured scopes. App types include Traditional Web, SPA, Native/Mobile, and Machine-to-Machine.API Resources and Scopes
API resources represent protected APIs (e.g.,https://api.yourapp.com). Each resource defines scopes — granular permissions like stream:live or content:read. Scopes appear in JWT access tokens.
Roles
Roles are named collections of scopes. Assign roles to users to grant permissions across multiple API resources. Roles can be marked as default (auto-assigned to new users) or restricted to M2M clients.Organizations
Organizations represent tenants — partner companies, enterprise clients, or business units. Members can have organization-scoped roles that are separate from their global roles.Rewards
The loyalty engine lets partners award points to users based on configurable rules. Points accumulate toward tier upgrades and can be redeemed for catalog items or mobile money cashback.API Authentication
mgPass uses three authentication methods:OAuth 2.0 Bearer Token
OAuth 2.0 Bearer Token
Used by client applications to access user data and perform user-scoped operations. Obtained through the standard OAuth 2.0 authorization code flow.
Admin Bearer Token
Admin Bearer Token
Bearer tokens with the
mgpass:admin scope, used by the admin console and administrative API clients. Required for all management endpoints.Partner API Key
Partner API Key
Static API keys issued to reward partners, sent via the
X-API-Key header. Used exclusively for the partner events endpoint.Base URLs
| Environment | URL |
|---|---|
| Production | https://auth.mgpass.net |
Next Steps
OAuth Flows
Implement authentication in your application
Register an App
Set up your OAuth client