OAuth 2.0 / OIDC Flows

Overview

mgPass implements OAuth 2.0 and OpenID Connect (OIDC) for authentication and authorization. Choose the flow that matches your application type.

Flow	Use Case
Authorization Code	Traditional web apps with a backend
Authorization Code + PKCE	SPAs and mobile/native apps
Client Credentials	Machine-to-machine (M2M)
Refresh Token	Renewing expired access tokens

Discovery Endpoint

The OIDC discovery document provides all endpoint URLs and supported features:

GET https://auth.mgpass.net/.well-known/openid-configuration

The JWKS endpoint for token verification:

GET https://auth.mgpass.net/.well-known/jwks.json

Authorization Code Flow

Best for traditional web applications with a server-side backend.

Redirect to authorize

Redirect the user to the authorization endpoint:

GET https://auth.mgpass.net/oidc/auth?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=openid profile email
  &state=random_state_value

Parameter	Required	Description
`response_type`	Yes	Must be `code`
`client_id`	Yes	Your application’s client ID
`redirect_uri`	Yes	Must match a registered redirect URI
`scope`	Yes	Space-separated scopes (include `openid` for OIDC)
`state`	Recommended	CSRF protection value

User authenticates

mgPass displays the sign-in screen. The user authenticates with email/password or a social connector. If consent is required, a consent screen is shown.

Receive authorization code

After successful auth, mgPass redirects to your redirect_uri with a code:

https://yourapp.com/callback?code=AUTH_CODE&state=random_state_value

Exchange code for tokens

Exchange the authorization code for tokens:

curl -X POST https://auth.mgpass.net/api/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_abc123...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "scope": "openid profile email"
}

Authorization Code + PKCE

Required for SPAs and mobile apps that cannot securely store a client secret.

Generate PKCE values

Generate a random code_verifier and derive the code_challenge:

function generateCodeVerifier() {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return btoa(String.fromCharCode(...array))
    .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}

async function generateCodeChallenge(verifier) {
  const hash = await crypto.subtle.digest(
    "SHA-256",
    new TextEncoder().encode(verifier)
  );
  return btoa(String.fromCharCode(...new Uint8Array(hash)))
    .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}

Redirect with PKCE parameters

GET https://auth.mgpass.net/oidc/auth?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=openid profile email
  &state=random_state_value
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256

Exchange code with verifier

Include code_verifier instead of client_secret:

const response = await fetch("https://auth.mgpass.net/api/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code: "AUTH_CODE",
    redirect_uri: "https://yourapp.com/callback",
    client_id: "YOUR_CLIENT_ID",
    code_verifier: "ORIGINAL_CODE_VERIFIER",
  }),
});

Client Credentials Flow

For server-to-server (M2M) communication where no user is involved.

curl -X POST https://auth.mgpass.net/api/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_M2M_CLIENT_ID" \
  -d "client_secret=YOUR_M2M_CLIENT_SECRET" \
  -d "scope=api:read api:write"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api:read api:write"
}

Client credentials tokens do not include a refresh_token or id_token since there is no user context.

Refresh Token Rotation

When an access token expires, use the refresh token to get a new pair:

curl -X POST https://auth.mgpass.net/api/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=rt_abc123..." \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

mgPass uses refresh token rotation. Each refresh returns a new refresh token and invalidates the old one. If a previously-used refresh token is submitted, all tokens for that session are revoked (replay detection).

Silent Authentication (`prompt=none`)

The prompt=none parameter lets you check if a user has an active mgPass session without showing any login UI. This is the foundation of cross-domain SSO and a fallback mechanism for token refresh. Request:

GET https://auth.mgpass.net/oidc/auth?
  prompt=none
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=openid+profile+email
  &state=RANDOM_STATE

Possible responses:

Outcome	Redirect	Next Step
User has active session and has authorized the app	`?code=AUTH_CODE&state=...`	Exchange code for tokens
No active session	`?error=login_required&state=...`	Show login button or redirect without `prompt=none`
Active session but first-time app	`?error=consent_required&state=...`	Redirect without `prompt=none` to show consent

When to use prompt=none:

SSO check on page load — silently check if the user is already logged in on another MG Digital property
Token renewal fallback — when a refresh token has expired, try silent auth before showing a login screen
Session validation — periodically confirm the user’s mgPass session is still active

The prompt=none request is a browser redirect, not a background API call. The user briefly sees a redirect to mgPass and back, but no login UI is shown.

Remember Me

The mgPass login screen includes a “Remember me for 30 days” checkbox that controls session persistence:

Setting	Cookie Type	Behavior
Checked (default)	Persistent cookie (30-day expiry)	User stays logged in across browser restarts. Session extends on each use (sliding window).
Unchecked	Session cookie	Session ends when the browser is closed. User must sign in again next time.

This affects the SSO session, not individual access tokens. Even with “Remember me” unchecked, access and refresh tokens work normally until the browser is closed.

The “Remember me” preference only applies to the mgPass session cookie. It does not change access token or refresh token lifetimes, which are configured per-application.

Scopes

Scope	Description
`openid`	Required for OIDC, returns an ID token
`profile`	User profile claims (name, avatar, etc.)
`email`	Email address and verification status
`phone`	Phone number and verification status
`offline_access`	Include a refresh token
Custom scopes	Defined per API resource (e.g., `stream:live`)

Getting Started

Authentication

User & Access Management

Rewards Integration

Advanced

SSO & Sessions

OAuth 2.0 / OIDC Flows

Overview

Discovery Endpoint

Authorization Code Flow

Authorization Code + PKCE

Client Credentials Flow

Refresh Token Rotation

Silent Authentication (`prompt=none`)

Remember Me

Scopes

Getting Started

Authentication

User & Access Management

Rewards Integration

Advanced

SSO & Sessions

Documentation Index

​Overview

​Discovery Endpoint

​Authorization Code Flow

​Authorization Code + PKCE

​Client Credentials Flow

​Refresh Token Rotation

​Silent Authentication (prompt=none)

​Remember Me

​Scopes

Overview

Discovery Endpoint

Authorization Code Flow

Authorization Code + PKCE

Client Credentials Flow

Refresh Token Rotation

Silent Authentication (`prompt=none`)

Remember Me

Scopes