Register a Third-Party Application

Admins use the web-admin Applications page at https://admin.muhajirstudio.com/ to register OIDC client applications that authenticate users through Muhajir Studio. Each admin-created application is a Public PKCE client: it receives a public client_id, does not receive a client_secret, and must use Authorization Code Flow with PKCE.

Access Requirements

Application management is protected in both the UI and API:

• The admin shell requires the login-web-admin permission.
• The Applications page requires the manage-applications permission.
• Admin API routes under /api/applications also require manage-applications.

Registration Flow

1. Open web-admin at https://admin.muhajirstudio.com/.
2. Go to Applications.
3. Select New application.
4. Fill in the application details, redirect configuration, and scopes.
5. Create the application.
6. Copy the generated client_id for the application developer.

The created application card shows the public credentials, allowed web origins, redirect paths, derived redirect URIs, selected scopes, and logo controls.

Application Fields

Client Name

clientName is required and is shown to admins and users. It is also synced to the underlying OAuth application name.

Validation:

• Required.
• Trimmed.
• Maximum length: 120 characters.

Description

clientDescription is optional. When provided, it is available to public application metadata and can be shown in user-facing authorization or consent UI.

Validation:

• Optional.
• Empty values are stored as null.
• Trimmed.
• Maximum length: 2000 characters.

Allowed Web Origins

allowedWebOrigins defines which browser origins belong to the application. These origins are also used by browser-safe third-party CORS for /api/auth/oauth2/token and /api/external/*.

Each origin must be an exact HTTP(S) origin, without path, query, fragment, credentials, or wildcard.

Valid examples:

https://app.example.com
https://staging.example.com
http://localhost:3000

Invalid examples:

https://app.example.com/auth/callback
https://*.example.com
https://user:pass@app.example.com
https://app.example.com?debug=true

Validation:

• Required.
• Minimum entries: 1.
• Maximum entries: 20.
• Each entry is normalized to its origin.
• Each entry has maximum length 255 before normalization.

Redirect Paths

redirectPaths defines callback paths for the application. Muhajir Studio combines every allowed web origin with every redirect path to derive the exact OAuth redirectUris stored for the client.

Valid examples:

/auth/callback
/oauth/callback
/login/provider/callback

Invalid examples:

auth/callback
//app.example.com/callback
/auth/callback?code=example
/auth/callback#fragment
https://app.example.com/auth/callback

Validation:

• Required.
• Minimum entries: 1.
• Maximum entries: 20.
• Must start with /.
• Must not start with //.
• Must not include host, query, fragment, or backslash.
• Each entry has maximum length 1024.

Derived Redirect URIs

Admins do not enter full OAuth redirect URIs directly. Muhajir Studio derives them from allowedWebOrigins and redirectPaths.

For example:

Allowed web origin	Redirect path	Derived redirect URI
https://app.example.com	/auth/callback	https://app.example.com/auth/callback
https://staging.example.com	/auth/callback	https://staging.example.com/auth/callback

OAuth authorize requests must still send one exact registered full redirect_uri. The server validates redirect_uri against the derived list and returns INVALID_REDIRECT_URI when it is not registered for the client.

Post-Verification Redirect Path

postVerificationRedirectPath is optional. It controls where users continue after email verification when an OIDC flow was paused for verification.

This value is path-only. When possible, Muhajir Studio combines it with the origin from the validated OAuth redirect_uri. If no caller redirect_uri context is available and the application has exactly one allowed web origin, Muhajir Studio can derive the post-verification URI from that single origin.

Validation:

• Optional.
• Empty values are stored as null.
• Uses the same path validation rules as redirectPaths.

Scopes

Every application must have at least one selected scope. Available scopes come from the app_scope table and are displayed with metadata from OIDC_SCOPE_METADATA.

Current supported scopes are:

Scope	Purpose
openid	Required OIDC identity scope. Enables stable subject identity.
profile	Allows profile claims such as name and picture when available.
email	Allows email and email verification status.
offline_access	Allows refresh-token based sessions where supported.
permissions	Allows permission claims and permission-based API fields.

Validation:

• Minimum selected scopes: 1.
• Maximum selected scopes: 50.
• Unknown scope IDs are rejected with UNKNOWN_SCOPE_IDS.

During authorization, dynamic applications use the scopes configured on the application. The authorize middleware rewrites the request scope to the registered application's configured scope set before the OIDC provider handles the request.

Generated Credentials

After creation, the application card shows:

Field	Value
client_id	Generated public client identifier.
client_type	Public PKCE.

No client_secret is generated or displayed. Developers must use Authorization Code Flow with PKCE and code_challenge_method=S256.

Logo Upload

Admins can upload an application logo from the application card. The logo is stored as a public object and the resulting URL is synced to the OAuth application icon.

If an upload fails, the admin UI keeps the application card available and shows an error toast with the failure reason.

Upload constraints:

• Form field name: file.
• Maximum size: 2 MiB.
• Allowed MIME types: image/png, image/jpeg, image/jpg, image/svg+xml, image/webp.
• Missing files return FILE_REQUIRED.
• Oversized files return FILE_TOO_LARGE.
• Unsupported file types return INVALID_FILE_TYPE.

Admin API Summary

The UI uses the following admin endpoints:

Method	Endpoint	Purpose
GET	/api/applications/scopes	List available app scopes.
GET	/api/applications	List registered applications.
GET	/api/applications/{id}	Get one application.
POST	/api/applications	Create an application.
PATCH	/api/applications/{id}	Update an application.
DELETE	/api/applications/{id}	Delete an application when allowed.
POST	/api/applications/{id}/logo	Upload or replace the application logo.

These endpoints validate request and response payloads with schemas from @drova/schemas.