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://pass.mediageneral.digital/.well-known/openid-configuration
GET https://pass.mediageneral.digital/.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://pass.mediageneral.digital/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://pass.mediageneral.digital/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"
{
"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://pass.mediageneral.digital/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://pass.mediageneral.digital/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://pass.mediageneral.digital/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"
{
"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://pass.mediageneral.digital/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).
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) |
