OIDC Endpoints

This reference lists the OIDC and OIDC-adjacent endpoints exposed by Muhajir Studio. Endpoint paths are shown relative to the API base URL: https://api.muhajirstudio.com/.

Discovery

GET /api/auth/.well-known/openid-configuration

Returns OpenID Connect discovery metadata, including:

• issuer
• authorization_endpoint
• token_endpoint
• userinfo_endpoint
• jwks_uri
• scopes_supported
• supported response, grant, subject, and signing metadata when available

Use discovery metadata rather than hardcoding issuer or JWKS URLs when your OIDC library supports it.

Authorization

GET /api/auth/oauth2/authorize

Browser redirect endpoint for Authorization Code Flow with PKCE.

Common query parameters:

Parameter	Required	Notes
client_id	yes	Public client ID.
redirect_uri	yes	Exact registered full redirect URI.
response_type	yes	Must be code.
scope	usually	Space-separated scopes; provider default is openid.
state	recommended	CSRF protection.
nonce	recommended	ID token replay protection.
code_challenge	yes	PKCE challenge.
code_challenge_method	yes	Must be S256.

The endpoint can redirect to login, consent, verification, or the client callback. It can also return 400 for invalid authorization requests such as an unregistered redirect_uri.

Token

POST /api/auth/oauth2/token

Exchanges authorization codes or refresh tokens. This is the standard endpoint third-party integrations should use.

Content type:

application/x-www-form-urlencoded

Authorization code request fields:

Field	Required	Notes
grant_type	yes	authorization_code.
code	yes	Authorization code from callback.
code_verifier	yes	Original PKCE verifier.
client_id	yes	Public client ID.
redirect_uri	yes	Same redirect URI used in authorization.

Refresh token request fields:

Field	Required	Notes
grant_type	yes	refresh_token.
refresh_token	yes	Refresh token from a prior token response.
client_id	yes	Public client ID.

client_secret is accepted by the generic OpenAPI schema as optional for clients that might support it, but admin-created Muhajir Studio applications are Public PKCE clients and do not have one.

Successful responses match OidcTokenResponse:

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

Errors follow the OAuth error shape:

{
  "error": "invalid_request",
  "error_description": "..."
}

UserInfo

GET /api/auth/oauth2/userinfo

Returns OIDC UserInfo claims allowed by the granted scopes.

Authentication:

Authorization: Bearer ACCESS_TOKEN

The response shape follows the ID token claims schema and can include standard claims such as sub, email, email_verified, name, picture, given_name, family_name, and the additional permissions claim when the access token has the permissions scope.

For stable third-party application user data, prefer GET /api/external/me unless you specifically need the OIDC UserInfo endpoint.

JWKS

GET /api/auth/jwks

Returns the JSON Web Key Set used to verify signed tokens.

Clients should use this endpoint, usually discovered from jwks_uri, to validate ID token signatures.

Public Scope Metadata

GET /api/public/oidc/scopes

Returns centralized OIDC scope labels, consent descriptions, developer descriptions, and claim lists.

The response includes:

{
  "items": [
    {
      "name": "openid",
      "label": "Verify your identity",
      "consentDescription": "Confirm your account identity.",
      "developerDescription": "Required OIDC scope. Allows the app to receive a stable subject identifier.",
      "claims": ["sub"]
    }
  ]
}

The current scope names are openid, profile, email, offline_access, and permissions.

Public Application Metadata

GET /api/public/applications/{clientId}

Returns user-facing metadata for a registered client:

• clientId
• clientName
• clientDescription
• clientLogoUrl
• postVerificationRedirectPath
• postVerificationRedirectUri

The endpoint also accepts an optional redirect_uri query parameter. When present and valid for the client, Muhajir Studio uses its origin to derive postVerificationRedirectUri from the application's path-only postVerificationRedirectPath.

First-Party Account Recovery

These endpoints support the hosted Muhajir Studio login experience. Third-party integrations should link users to the hosted login UI instead of calling these endpoints directly.

POST /api/auth/request-password-reset

Requests a password reset email.

JSON request body:

{
  "email": "user@example.com",
  "redirectTo": "https://auth.example.com/reset-password"
}

The response is intentionally generic to avoid revealing whether an email address exists. If a matching account exists and email delivery is configured, the user receives a reset link. The reset token expires after 30 minutes.

GET /api/auth/reset-password/{token}

Validates a reset token from email and redirects the browser to the redirectTo URL with a token query parameter. Invalid or expired tokens redirect with error=INVALID_TOKEN.

POST /api/auth/reset-password

Sets the new password for a valid reset token.

JSON request body:

{
  "token": "RESET_TOKEN",
  "newPassword": "new-secure-password"
}

Successful resets revoke existing sessions. Users must sign in again with the new password.

First-Party Cookie Token Helpers

These endpoints are first-party helpers. Third-party integrations should use /api/auth/oauth2/token unless explicitly instructed otherwise.

POST /api/auth/oauth2/token/cookie

Wraps the standard token endpoint and stores any returned refresh_token in an HTTP-only cookie. It returns the token response without refresh_token in the JSON body.

Accepted grant types:

• authorization_code
• refresh_token

For refresh_token grants, the refresh token is read from the refresh cookie. If the cookie is missing, the endpoint returns 401 with invalid_grant.

The refresh cookie:

• is HTTP-only
• uses configured secure and sameSite settings
• is scoped to /api/auth/oauth2/token

POST /api/auth/oauth2/token/cookie-logout

Clears the first-party OIDC refresh cookie and returns 204 No Content.