Application Lifecycle Management

This page explains how registered OIDC applications behave after creation: what can be edited, how updates affect OAuth authorization, what happens when scopes or redirect configuration change, and how deletion works.

List and Review Applications

The Applications page lists registered applications in descending creation order. Each card shows:

• Client name.
• Creation date.
• client_id with copy action.
• client_type, shown as Public PKCE.
• Allowed web origins.
• Redirect paths.
• Derived redirect URIs.
• Selected OIDC scopes.
• Logo upload control.
• Edit action.
• Delete action when the application is not system-reserved.

Editable Fields

Admins can edit these fields:

Field	Effect
clientName	Updates the application display name and underlying OAuth application name.
clientDescription	Updates optional public application metadata.
allowedWebOrigins	Recomputes derived redirect URIs and browser-safe CORS origins.
redirectPaths	Recomputes derived redirect URIs.
postVerificationRedirectPath	Updates OIDC metadata used by verification continuation.
scopeIds	Replaces the application's allowed OIDC scope set.
Logo	Updates the public logo URL and underlying OAuth application icon.

The application client_id and client_type are not editable. Admin-created applications remain Public PKCE clients and never receive a client_secret.

Redirect Configuration Changes

When allowedWebOrigins or redirectPaths change, Muhajir Studio derives a new full redirect URI set and syncs that set to the underlying OAuth application.

Example:

Allowed web origins	Redirect paths	Resulting redirect URIs
https://app.example.com	/auth/callback	https://app.example.com/auth/callback
https://app.example.com, https://staging.example.com	/auth/callback	https://app.example.com/auth/callback, https://staging.example.com/auth/callback

After this change, authorization requests must use one of the currently derived redirect URIs. Old callback URLs stop working as soon as they are no longer in the derived set.

Scope Changes

Updating scopes replaces the application's scope assignments. The API first removes existing rows from application_scope, validates the new scope IDs, and inserts the new set.

During OIDC authorization, dynamic applications use the application's configured scopes. The authorization middleware rewrites the requested scope value to the configured scope set before the OIDC provider processes the request.

Practical effect:

• Adding a scope allows future authorization flows to grant that scope.
• Removing a scope prevents future authorization flows from granting that scope.
• Existing access tokens are not revoked by a normal scope update.
• If immediate revocation is required, delete and recreate the application or implement a dedicated revocation operation.

Post-Verification Redirect Changes

Updating postVerificationRedirectPath stores the path in the application row and syncs it into OAuth application metadata.

When public metadata is requested with a redirect_uri query parameter, Muhajir Studio verifies the redirect_uri is registered for the client before combining its origin with postVerificationRedirectPath. This prevents unregistered origins from controlling verification continuation.

If there is no caller redirect_uri, Muhajir Studio can only derive postVerificationRedirectUri when the application has exactly one allowed web origin.

Logo Changes

Uploading a logo stores a public object under the application ID and updates both:

• clientLogoUrl on the application response.
• The underlying OAuth application icon value.

Uploading a new logo replaces the displayed logo URL. The upload endpoint enforces file presence, supported image MIME types, and a 2 MiB size limit.

Delete Behavior

Deleting an application is a destructive operation. For non-system applications, deletion:

1. Loads the application by id.
2. Deletes OAuth access tokens for the application's clientId.
3. Deletes saved OAuth consents for the application's clientId.
4. Deletes the underlying OAuth application row.
5. Deletes the application row.
6. Attempts to delete the stored logo object after the database deletion succeeds.
7. Returns 204 No Content on success.

The confirmation dialog warns admins that existing OAuth state for this client will be revoked. After deletion, the old client_id should no longer be used by third-party applications.

Possible delete responses:

Status	Error	Meaning
204	none	Application deleted.
400	INVALID_ID	The id path parameter is not a valid UUID.
403	APPLICATION_PROTECTED	The application is system-reserved and cannot be deleted.
404	NOT_FOUND	No application exists for the given ID.

Reserved web-admin Application

The admin application client ID is system-reserved and should stay web-admin in every environment. Use the deployed admin origin and redirect URI settings to point the client at the production admin domain. The reserved application is visible in application management when seeded so admins can review its metadata, but it is protected from deletion.

The UI hides the delete action for reserved clients. The backend also enforces this rule; attempting to delete a reserved client returns:

{
  "error": "APPLICATION_PROTECTED",
  "message": "System-reserved applications cannot be deleted"
}

Reserved-client protection includes RESERVED_OIDC_CLIENT_IDS from @drova/schemas plus the API runtime WEB_ADMIN_CLIENT_ID value.

Error Handling

Application management endpoints return structured errors for common validation and lifecycle failures:

Error	When it happens
INVALID_BODY	Create or update payload fails schema validation.
INVALID_ID	URL id parameter is not a UUID.
UNKNOWN_SCOPE_IDS	Create or update references scope IDs that do not exist.
NOT_FOUND	Requested application does not exist.
APPLICATION_PROTECTED	Delete was attempted for a reserved application.
FILE_REQUIRED	Logo upload did not include a file.
FILE_TOO_LARGE	Logo file exceeds 2 MiB.
INVALID_FILE_TYPE	Logo file MIME type is not supported.
INTERNAL_ERROR	Unexpected server-side failure.

Operational Notes

• Treat redirect configuration updates as potentially breaking changes for third-party applications.
• Share the generated client_id and exact derived redirect URIs with developers.
• Do not share or document a client_secret; admin-created applications do not have one.
• Scope changes affect future authorization flows, but normal updates do not automatically revoke already-issued access tokens.
• Delete and recreate only when you intend to invalidate the old client_id and remove stored OAuth access tokens and consents.