Applications (OAuth Clients)

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 your ecosystem is a registered application: your web apps, mobile apps, 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:

Traditional Web

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.

Single Page Application (SPA)

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.

Native / Mobile

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: Your mobile app or a native desktop client.

Machine-to-Machine (M2M)

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: A rewards backend calling the mgPass Management API to look up user profiles. A ticketing service calling the rewards API to publish ticket purchase events.

Creating an Application via Admin Console

Navigate to Applications

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

Click Create Application

Click the Create Application button. Fill in:

Name — displayed to users on the consent screen (e.g., “My App”, “Partner Portal”)
Type — select the appropriate type from the dropdown
Description — optional, shown on the consent screen

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.

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)

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://auth.mgpass.net/api/clients \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App Web",
    "type": "web",
    "redirect_uris": ["https://yourapp.com/callback"],
    "post_logout_uris": ["https://yourapp.com"],
    "allowed_scopes": ["openid", "profile", "email", "stream:live"],
    "cors_origins": [],
    "access_token_ttl": 3600,
    "refresh_token_ttl": 2592000
  }'

Response:

{
  "id": "app_abc123",
  "name": "My App Web",
  "type": "web",
  "secret": "cs_live_xxxxxxxxxxxxxxxx",
  "redirect_uris": ["https://yourapp.com/callback"],
  "allowed_scopes": ["openid", "profile", "email", "stream:live"]
}

Configuration Reference

Field	Type	Default	Description
`name`	string	required	Display name on consent screen
`type`	string	required	`web`, `spa`, `native`, `m2m`
`redirect_uris`	string[]	required	Allowed OAuth callback URLs (exact match)
`post_logout_uris`	string[]	`[]`	Allowed post-logout redirect URLs
`allowed_scopes`	string[]	`[]`	Scopes this app can request
`cors_origins`	string[]	`[]`	CORS origins for SPA/browser requests
`access_token_ttl`	integer	`3600`	Access token lifetime in seconds (1 hour)
`refresh_token_ttl`	integer	`2592000`	Refresh token lifetime in seconds (30 days)
`refresh_token_rotation`	boolean	`true`	Issue new refresh token on each refresh
`branding`	object	`null`	Per-app consent screen branding
`auth_methods`	string[]	all	Restrict allowed auth methods
`access_control`	object	all users	Restrict 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.yourapp.com/logo.png",
    "primary_color": "#FF6B00",
    "app_name": "My App"
  }
}

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://auth.mgpass.net/api/clients/app_abc123/rotate-secret \
  -H "Authorization: Bearer ADMIN_TOKEN"

A new secret is generated and returned
Update your application’s environment variables with the new secret
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…	Use	Why
A website with a backend	Traditional Web	Secret stays on server, most secure
A React/Vue/Angular frontend	SPA	No backend to store secret, uses PKCE
An iOS or Android app	Native	Can’t trust embedded secrets, uses PKCE
A backend service calling APIs	M2M	No user involved, uses client credentials
A Next.js app with server components	Traditional Web	Has a server-side runtime
A static site (Astro, Hugo)	SPA	No server-side runtime

SSO Behavior

All registered applications benefit from mgPass Single Sign-On automatically:

Existing session? If the user has an active mgPass session (from any app), they are logged in instantly with no login screen. mgPass uses a prompt=none redirect to issue an authorization code silently.
First-time authorization: The first time a user accesses your app, they see a consent screen asking to approve the requested scopes. After approval, subsequent logins are instant.
No configuration needed: SSO is enabled by default for every application. You do not need to opt in or configure anything beyond the standard OAuth setup.

The consent screen is only shown once per user per application. After the user approves, they will never see it again for that app (unless you add new scopes).

For a detailed guide on implementing SSO in your application, including cross-domain patterns and code examples, see the SSO Guide.

Next Steps

SSO Guide — implement seamless single sign-on in your app
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

Getting Started

Authentication

User & Access Management

Rewards Integration

Advanced

SSO & Sessions

Applications (OAuth Clients)

What is an Application?

Application Types

Creating an Application via Admin Console

Creating an Application via API

Configuration Reference

Per-App Branding

Access Control

Secret Rotation

Which Type Should I Use?

SSO Behavior

Next Steps

Getting Started

Authentication

User & Access Management

Rewards Integration

Advanced

SSO & Sessions

​What is an Application?

​Application Types

​Creating an Application via Admin Console

​Creating an Application via API

​Configuration Reference

​Per-App Branding

​Access Control

​Secret Rotation

​Which Type Should I Use?

​SSO Behavior

​Next Steps

What is an Application?

Application Types

Creating an Application via Admin Console

Creating an Application via API

Configuration Reference

Per-App Branding

Access Control

Secret Rotation

Which Type Should I Use?

SSO Behavior

Next Steps