Skip to main content

​
What is an Application?

An Application in mgPass represents any platform, website, or service that needs to authenticate users. When you register an application, mgPass issues it a Client ID and (for server-side apps) a Client Secret that it uses to initiate the OAuth 2.0 login flow. Every platform in the MG Digital ecosystem is a registered application: adesa+, 3News, mgTix, the admin console itself, and any third-party integrations.

​
Application Types

Choosing the right type determines how the application authenticates and what security measures are enforced:
For: Server-rendered apps with a backend (Next.js, Django, Rails, Express, Laravel)How it works: The app’s backend exchanges an authorization code for tokens using the client secret. The secret is never exposed to the browser.Security:
  • Has a client secret (stored on the server)
  • Code exchange happens server-to-server
  • Most secure option for web apps
Example: The mgPass Admin Console itself is a Traditional Web application.
For: Client-side JavaScript apps (React, Vue, Angular, Svelte)How it works: The app runs entirely in the browser. Since there’s no server to securely store a secret, it uses PKCE (Proof Key for Code Exchange) instead.Security:
  • No client secret (would be exposed in browser code)
  • PKCE challenge/verifier prevents authorization code interception
  • Requires CORS origins to be configured
Example: A React dashboard that authenticates against mgPass.
For: iOS, Android, desktop, and CLI applicationsHow it works: Similar to SPA, uses PKCE since the app binary can be decompiled and secrets extracted. Uses custom URI schemes or deep links for callbacks (e.g., myapp://callback).Security:
  • No client secret
  • PKCE required
  • Custom redirect URI schemes allowed
Example: The adesa+ mobile app, or the future mgOne super-app.
For: Backend services that call APIs without a user presentHow it works: The service authenticates directly with its client ID and secret using the Client Credentials grant. No user login is involved — the service gets its own access token with scopes defined by its M2M role.Security:
  • Has a client secret
  • No user interaction
  • Token scopes come from M2M roles, not user roles
Example: mgRewards backend calling the mgPass Management API to look up user profiles. mgTix calling mgRewards to publish ticket purchase events.

​
Creating an Application via Admin Console

1

Navigate to Applications

In the mgPass Admin Console, click Applications in the sidebar.
2

Click Create Application

Click the Create Application button. Fill in:
  • Name — displayed to users on the consent screen (e.g., “adesa+”, “3News”)
  • Type — select the appropriate type from the dropdown
  • Description — optional, shown on the consent screen
3

Configure Redirect URIs

Add the URLs where mgPass should redirect users after login:
  • Production: https://yourapp.com/callback
  • Staging: https://staging.yourapp.com/callback
  • Local dev: http://localhost:3000/callback
Redirect URIs must match exactly — no wildcards. A mismatch will cause the OAuth flow to fail with redirect_uri_mismatch.
4

Set Allowed Scopes

Choose which user data this app can request:
  • openid — required for OIDC
  • profile — user’s name and avatar
  • email — user’s email address
  • Custom scopes from your API Resources (e.g., stream:live, events:read)
5

Save and Store the Secret

After creation, you’ll see the Client ID and Client Secret (for web/M2M types).
The client secret is shown only once. Copy and store it securely (e.g., in your deployment’s environment variables). It cannot be retrieved later — only rotated.

​
Creating an Application via API

curl -X POST https://pass.mediageneral.digital/api/clients \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "adesa+ Web",
    "type": "web",
    "redirect_uris": ["https://adesa.com.gh/callback"],
    "post_logout_uris": ["https://adesa.com.gh"],
    "allowed_scopes": ["openid", "profile", "email", "stream:live"],
    "cors_origins": [],
    "access_token_ttl": 3600,
    "refresh_token_ttl": 2592000
  }'
Response: 
{
  "id": "app_abc123",
  "name": "adesa+ Web",
  "type": "web",
  "secret": "cs_live_xxxxxxxxxxxxxxxx",
  "redirect_uris": ["https://adesa.com.gh/callback"],
  "allowed_scopes": ["openid", "profile", "email", "stream:live"]
}

​
Configuration Reference

FieldTypeDefaultDescription
namestringrequiredDisplay name on consent screen
typestringrequiredweb, spa, native, m2m
redirect_urisstring[]requiredAllowed OAuth callback URLs (exact match)
post_logout_urisstring[][]Allowed post-logout redirect URLs
allowed_scopesstring[][]Scopes this app can request
cors_originsstring[][]CORS origins for SPA/browser requests
access_token_ttlinteger3600Access token lifetime in seconds (1 hour)
refresh_token_ttlinteger2592000Refresh token lifetime in seconds (30 days)
refresh_token_rotationbooleantrueIssue new refresh token on each refresh
brandingobjectnullPer-app consent screen branding
auth_methodsstring[]allRestrict allowed auth methods
access_controlobjectall usersRestrict to users with specific roles

​
Per-App Branding

When a user logs in through your app, you can customize what they see on the consent screen: 
{
  "branding": {
    "logo_url": "https://cdn.adesa.com.gh/logo.png",
    "primary_color": "#FF6B00",
    "app_name": "adesa+"
  }
}
The user sees your app’s logo and name instead of the generic mgPass branding. This builds trust — users recognize the platform they came from.

​
Access Control

Restrict who can log into an application: 
{
  "access_control": {
    "type": "roles",
    "roles": ["mgpass:admin"]
  }
}
This is useful for internal tools — only users with the mgpass:admin role can authenticate. All other users are denied at the consent step.

​
Secret Rotation

Rotate a client secret without downtime: 
curl -X POST https://pass.mediageneral.digital/api/clients/app_abc123/rotate-secret \
  -H "Authorization: Bearer ADMIN_TOKEN"
  1. A new secret is generated and returned
  2. Update your application’s environment variables with the new secret
  3. The old secret is immediately invalidated
Rotate secrets at least every 90 days, or immediately if you suspect a leak.

​
Which Type Should I Use?

Your app is…UseWhy
A website with a backendTraditional WebSecret stays on server, most secure
A React/Vue/Angular frontendSPANo backend to store secret, uses PKCE
An iOS or Android appNativeCan’t trust embedded secrets, uses PKCE
A backend service calling APIsM2MNo user involved, uses client credentials
A Next.js app with server componentsTraditional WebHas a server-side runtime
A static site (Astro, Hugo)SPANo server-side runtime

​
Next Steps

  • OAuth Flows — implement the login flow for your app type
  • RBAC — control what users can do in your app
  • Per-App Webhooks — get notified when users interact with your app