Autentikasi API

Halaman ini menjelaskan cara aplikasi pihak ketiga melakukan authentication ke external APIs Muhajir Studio dan API surfaces mana yang ditujukan untuk external integrations.

URL Dasar Layanan

Gunakan URL layanan produksi berikut untuk alur API, login, dan admin:

Service	Base URL	Digunakan untuk
API	https://api.muhajirstudio.com/	OIDC endpoints, token exchange, public metadata, dan /api/external/*.
Main web	https://login.muhajirstudio.com/	Login, signup, email verification, dan consent pages.
Admin web	https://admin.muhajirstudio.com/	Admin application configuration UI.

Untuk integrasi sandbox atau staging, gunakan service URLs ekuivalen yang diberikan oleh kontak Muhajir Studio Anda.

API Base URL

Gunakan API base URL untuk environment target dan tambahkan documented path.

URL produksi untuk current-user endpoint eksternal: https://api.muhajirstudio.com/api/external/me.

Jika aplikasi Anda mendukung beberapa environment, buat service URLs configurable di aplikasi Anda sendiri.

External API Namespace

Third-party integrations sebaiknya memperlakukan /api/external/* sebagai stable external API namespace.

Jangan memanggil first-party session endpoints seperti /api/me/* dari third-party integrations kecuali endpoint tertentu secara eksplisit didokumentasikan sebagai public. First-party endpoints dapat bergantung pada cookie sessions dan asumsi internal UI, sedangkan external endpoints dirancang untuk OIDC bearer access tokens.

Bearer Token Authentication

External APIs membutuhkan OIDC access token di header Authorization:

Authorization: Bearer ACCESS_TOKEN

Server hanya menerima scheme Bearer. Cookie-only sessions tidak diterima oleh /api/external/me.

Bearer token resolver memeriksa bahwa:

• header Authorization ada
• scheme adalah Bearer
• access token ada di OIDC access-token store
• access token belum expired
• access token terkait dengan user

Jika salah satu pemeriksaan gagal, external APIs mengembalikan:

{
  "error": "UNAUTHORIZED"
}

dengan HTTP status 401.

Required Scopes

Endpoint-specific scope checks terjadi setelah bearer authentication. Misalnya, GET /api/external/me membutuhkan scope openid.

Jika bearer token valid tetapi tidak memiliki required scope, endpoint mengembalikan 403 dengan missingScopes:

{
  "error": "FORBIDDEN",
  "missingScopes": ["openid"]
}

Browser CORS Rules

Browser-based third-party apps hanya dapat memanggil route-scoped third-party endpoints dari registered origins.

Dynamic third-party CORS diaktifkan untuk:

• POST /api/auth/oauth2/token
• OPTIONS /api/auth/oauth2/token
• /api/external/*

Allowed browser origins berasal dari nilai allowedWebOrigins pada registered application. Server menyimpan cache daftar registered-origin selama 60 detik.

CORS behavior:

Setting	Value
Credentials	false
Methods	GET, POST, OPTIONS
Allowed headers	Authorization, Content-Type
Preflight success status	204

Jika browser request tidak memiliki Origin, atau origin tidak terdaftar, dynamic third-party CORS tidak mengizinkan request. Daftarkan exact web origin di web-admin sebelum membuat browser-based token atau external API calls.

Public Metadata Endpoints

Beberapa public metadata endpoints mendukung login, consent, dan integration setup flows. Endpoint ini tidak membutuhkan OIDC bearer token.

GET /api/public/oidc/scopes

Mengembalikan metadata untuk supported OIDC scopes:

{
  "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.

GET /api/public/applications/{clientId}

Mengembalikan user-facing metadata untuk OIDC client:

{
  "clientId": "client-id",
  "clientName": "Example App",
  "clientDescription": "Example description",
  "clientLogoUrl": "https://cdn.example.com/logo.png",
  "postVerificationRedirectPath": "/welcome",
  "postVerificationRedirectUri": "https://app.example.com/welcome"
}

Query parameter opsional redirect_uri menyediakan caller context. Jika valid untuk client, Muhajir Studio memakai origin-nya untuk menurunkan postVerificationRedirectUri dari path-only postVerificationRedirectPath milik aplikasi.

Errors:

Status	Error	Arti
400	INVALID_CLIENT_ID	Parameter clientId tidak valid.
404	NOT_FOUND	Tidak ada dynamic atau static application untuk client ID tersebut.
500	INTERNAL_ERROR	Application lookup gagal secara tidak terduga.

OAuth Token Endpoint

Third-party apps menukar authorization codes dan refresh tokens di:

POST /api/auth/oauth2/token

Endpoint ini tidak berada di bawah /api/external/*, tetapi sengaja termasuk dalam third-party CORS karena browser PKCE clients perlu memanggilnya.

Gunakan request application/x-www-form-urlencoded. Aplikasi yang dibuat admin adalah Public PKCE clients dan tidak memiliki client_secret.

Error Model

External API errors memakai JSON response bodies dengan string error. Beberapa response menyertakan field tambahan seperti missingScopes.

Common external API errors:

Status	Error	Arti
401	UNAUTHORIZED	Bearer token tidak ada, malformed, expired, tidak dikenal, atau tidak terkait dengan user.
403	FORBIDDEN	Bearer token valid tetapi tidak memiliki required scope.
404	USER_NOT_FOUND	Token subject tidak lagi terhubung ke user yang ada.
500	INTERNAL_ERROR	Unexpected server error.

OAuth endpoints mengikuti OAuth error responses seperti invalid_request atau invalid_grant.

Implementation Checklist

• Gunakan Authorization Code Flow with PKCE untuk mendapatkan OIDC access token.
• Simpan token sesuai tipe aplikasi dan threat model Anda.
• Kirim Authorization: Bearer ACCESS_TOKEN ke /api/external/*.
• Request hanya scopes yang dibutuhkan integrasi Anda.
• Daftarkan browser origins di allowedWebOrigins sebelum memanggil token atau external API endpoints dari browser.
• Gunakan /api/external/me untuk third-party current-user data, bukan first-party /api/me/* endpoints.