Overview

Muhajir Studio can act as an OpenID Connect (OIDC) login provider for third-party applications. A registered application redirects users to Muhajir Studio to sign in, Muhajir Studio handles authentication, email verification, consent, and token issuance, and the application can use the resulting bearer access token to call Muhajir Studio's external API.

Production Service URLs

Use these production service URLs when integrating with Muhajir Studio:

Service	Base URL	Used for
API	https://api.muhajirstudio.com/	OIDC endpoints, token exchange, public metadata, and /api/external/*.
Main web	https://login.muhajirstudio.com/	Login, signup, email verification, and consent pages.
Admin web	https://admin.muhajirstudio.com/	Application registration and management in web-admin.

For sandbox or staging integrations, use the equivalent service URLs provided by your Muhajir Studio contact.

What the Login Provider Provides

Login Provider Role

Third-party applications start login by sending the browser to Muhajir Studio's OIDC authorization endpoint:

GET /api/auth/oauth2/authorize

Muhajir Studio's OIDC provider requires Authorization Code Flow with PKCE. The authorization request must use response_type=code, a code_challenge, and code_challenge_method=S256. Plain code challenges are not accepted.

If a user is not signed in, Muhajir Studio redirects them to the web-main login UI. If the user is signed in but their email is not verified, Muhajir Studio redirects them to /verify-email before authorization can complete. The original OIDC parameters are preserved through login, signup, verification, and the email-verified screen so the authorization request can resume safely.

API Provider Role

After the application receives an authorization code, it exchanges the code at:

POST /api/auth/oauth2/token

The token response can include an access_token, id_token, optional refresh_token, expires_in, token_type, and scope. External API calls use the access token as a bearer token.

The stable third-party current-user endpoint is:

GET /api/external/me

This endpoint requires an OIDC bearer access token and the openid scope. Optional fields are returned only when the access token has the matching scopes:

Scope	Adds
openid	sub
profile	name, picture
email	email, emailVerified
permissions	permissions

Admin-Managed Clients

Applications are registered by Muhajir Studio admins in web-admin. Admin-created clients are Public PKCE clients:

• The application receives a public client_id.
• No client_secret is issued.
• The application must use Authorization Code Flow with PKCE.
• Admins configure allowedWebOrigins and redirectPaths; Muhajir Studio derives the exact OAuth redirectUris from every origin/path combination.
• Admins choose the application's allowed scopes. Muhajir Studio applies the registered application's configured scope set during authorization.

Integration Flow at a Glance

1. Admin Setup

An admin registers the third-party application in web-admin:

1. Enter a client name and optional description for user-facing consent screens.
2. Add one or more allowed web origins, for example https://app.example.com.
3. Add one or more redirect paths, for example /auth/callback.
4. Optionally add a post-verification redirect path, for example /welcome.
5. Select allowed OIDC scopes.
6. Share the generated client_id with the application developer.

Muhajir Studio derives full redirect URIs from the configured origins and paths. For example, https://app.example.com plus /auth/callback becomes https://app.example.com/auth/callback.

2. User Login

The application redirects the user to /api/auth/oauth2/authorize with client_id, an exact registered redirect_uri, PKCE parameters, and state/nonce values. Muhajir Studio handles these user-facing steps:

1. Sign in or sign up through web-main.
2. Verify email when required.
3. Review the consent screen with the registered application name, logo, description, and scope descriptions.
4. Approve or deny access.

Consent approval is disabled if Muhajir Studio cannot load the registered application metadata for the request.

3. Developer Callback and API Access

After approval, Muhajir Studio redirects back to the application's exact redirect_uri with an authorization code and the original state. The application then:

1. Verifies state.
2. Exchanges code and code_verifier at /api/auth/oauth2/token.
3. Validates the id_token when used for local sign-in.
4. Calls /api/external/me with Authorization: Bearer access_token to retrieve the scope-filtered Muhajir Studio user profile.

Where to Go Next

• Use the Public PKCE Login Quickstart for the fastest working integration.
• Use Register a Third-Party Application when setting up app configuration in web-admin.
• Use OIDC Endpoints for protocol-level endpoint details.
• Use Current User API for the /api/external/me response contract.