Endpoint OIDC

Reference ini mencantumkan OIDC dan OIDC-adjacent endpoints yang diekspos oleh Muhajir Studio. Endpoint paths ditampilkan relatif terhadap API base URL: https://api.muhajirstudio.com/.

Discovery

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

Mengembalikan OpenID Connect discovery metadata, termasuk:

• issuer
• authorization_endpoint
• token_endpoint
• userinfo_endpoint
• jwks_uri
• scopes_supported
• supported response, grant, subject, dan signing metadata jika tersedia

Gunakan discovery metadata daripada hardcoding issuer atau JWKS URLs jika OIDC library Anda mendukungnya.

Authorization

GET /api/auth/oauth2/authorize

Browser redirect endpoint untuk Authorization Code Flow with PKCE.

Query parameters umum:

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

Endpoint ini dapat redirect ke login, consent, verification, atau client callback. Endpoint ini juga dapat mengembalikan 400 untuk invalid authorization requests seperti redirect_uri yang tidak terdaftar.

Token

POST /api/auth/oauth2/token

Menukar authorization codes atau refresh tokens. Ini adalah standard endpoint yang sebaiknya digunakan third-party integrations.

Content type:

application/x-www-form-urlencoded

Authorization code request fields:

Field	Wajib	Catatan
grant_type	yes	authorization_code.
code	yes	Authorization code dari callback.
code_verifier	yes	Original PKCE verifier.
client_id	yes	Public client ID.
redirect_uri	yes	Redirect URI yang sama dengan authorization.

Refresh token request fields:

Field	Wajib	Catatan
grant_type	yes	refresh_token.
refresh_token	yes	Refresh token dari token response sebelumnya.
client_id	yes	Public client ID.

client_secret diterima oleh generic OpenAPI schema sebagai opsional untuk client yang mungkin mendukungnya, tetapi aplikasi Muhajir Studio yang dibuat admin adalah Public PKCE clients dan tidak memilikinya.

Response berhasil mengikuti OidcTokenResponse:

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

Errors mengikuti OAuth error shape:

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

UserInfo

GET /api/auth/oauth2/userinfo

Mengembalikan OIDC UserInfo claims yang diizinkan oleh granted scopes.

Authentication:

Authorization: Bearer ACCESS_TOKEN

Response shape mengikuti ID token claims schema dan dapat menyertakan standard claims seperti sub, email, email_verified, name, picture, given_name, family_name, serta additional permissions claim saat access token memiliki scope permissions.

Untuk stable third-party application user data, gunakan GET /api/external/me kecuali Anda secara khusus membutuhkan OIDC UserInfo endpoint.

JWKS

GET /api/auth/jwks

Mengembalikan JSON Web Key Set yang digunakan untuk memverifikasi signed tokens.

Clients sebaiknya memakai endpoint ini, biasanya ditemukan dari jwks_uri, untuk memvalidasi ID token signatures.

Public Scope Metadata

GET /api/public/oidc/scopes

Mengembalikan centralized OIDC scope labels, consent descriptions, developer descriptions, dan claim lists.

Response mencakup:

{
  "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"]
    }
  ]
}

Scope names saat ini adalah openid, profile, email, offline_access, dan permissions.

Public Application Metadata

GET /api/public/applications/{clientId}

Mengembalikan user-facing metadata untuk registered client:

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

Endpoint ini juga menerima query parameter opsional redirect_uri. Jika ada dan valid untuk client, Muhajir Studio memakai origin-nya untuk menurunkan postVerificationRedirectUri dari path-only postVerificationRedirectPath milik aplikasi.

First-Party Account Recovery

Endpoint berikut mendukung hosted login experience Muhajir Studio. Third-party integrations sebaiknya mengarahkan user ke hosted login UI, bukan memanggil endpoint ini secara langsung.

POST /api/auth/request-password-reset

Meminta email reset password.

JSON request body:

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

Response dibuat generik untuk menghindari kebocoran apakah alamat email terdaftar. Jika akun ditemukan dan email delivery sudah dikonfigurasi, user menerima reset link. Reset token berlaku selama 30 menit.

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

Memvalidasi reset token dari email lalu me-redirect browser ke URL redirectTo dengan query parameter token. Token yang invalid atau expired akan redirect dengan error=INVALID_TOKEN.

POST /api/auth/reset-password

Mengatur password baru untuk reset token yang valid.

JSON request body:

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

Reset yang berhasil akan mencabut session yang ada. User harus sign in ulang memakai password baru.

First-Party Cookie Token Helpers

Endpoint ini adalah first-party helpers. Third-party integrations sebaiknya memakai /api/auth/oauth2/token kecuali secara eksplisit diminta sebaliknya.

POST /api/auth/oauth2/token/cookie

Membungkus standard token endpoint dan menyimpan refresh_token yang dikembalikan ke HTTP-only cookie. Endpoint ini mengembalikan token response tanpa refresh_token di JSON body.

Accepted grant types:

• authorization_code
• refresh_token

Untuk grant refresh_token, refresh token dibaca dari refresh cookie. Jika cookie tidak ada, endpoint mengembalikan 401 dengan invalid_grant.

Refresh cookie:

• HTTP-only
• memakai configured secure dan sameSite settings
• scoped ke /api/auth/oauth2/token

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

Menghapus first-party OIDC refresh cookie dan mengembalikan 204 No Content.