Operational Readiness

Use this checklist before operating Muhajir Studio integrations in production.

Production Service Inventory

Service	Production URL	Operational responsibility
API	https://api.muhajirstudio.com/	OIDC issuer, token exchange, external API, OpenAPI, and health checks.
Main web	https://login.muhajirstudio.com/	Hosted login, signup, verification, and consent UX.
Admin web	https://admin.muhajirstudio.com/	Application registration, scope management, and RBAC administration.

Keep a deployment inventory for each environment you operate: production, staging, sandbox, or local development. The issuer, login URL, consent URL, admin origin, and registered application origins must all point to the matching environment.

Deployment Configuration Checklist

Before launch, verify that operators have configured:

Area	Readiness check
Database	PostgreSQL host, credentials, database name, and migrations are ready.
Auth secret	The authentication signing secret is strong, private, and stable across app restarts.
OIDC issuer	The issuer URL matches the public production API origin.
Login and consent URLs	URLs point to the production main web app.
Admin trusted origins	The production admin origin is trusted by the API.
Static CORS	First-party web origins are allowed only where needed.
Third-party CORS	Dynamic registered origins are managed through application registration.
Refresh-cookie settings	Secure cookies and SameSite policy match production HTTPS deployment.
Settings encryption	The service-settings encryption key is present and backed up securely.
Object storage	Public asset storage for profile photos, application logos, and branding is reachable.
Email service	Verification email delivery is configured, enabled, and tested.

Do not rotate signing or encryption secrets without a migration/incident plan. Rotation can invalidate sessions, refresh tokens, or encrypted service settings.

Production Pause Mode

Use the Pulumi drova:deploymentMode setting when production must be temporarily paused without discarding durable state:

• active is the normal serving mode.
• paused keeps the stack managed, sets Cloud SQL to a stopped activation policy, and removes public Cloud Run invoker access for the API and landing services.

Pause mode keeps Cloud Storage buckets, database data, secrets, Artifact Registry images, DNS, certificates, and load balancer resources intact so operators can resume from the same Pulumi state. Before applying a pause preview, confirm Pulumi is not destroying Cloud SQL, GCS buckets, Secret Manager secrets, Artifact Registry, or the DNS zone. After resuming to active, run the Cloud Run smoke job and verify /health before serving production traffic again.

Database Migrations and Seeds

Run database migrations before serving production traffic:

npm --workspace api-main run db:migrate

Migrations are tracked in the _migrations table and run in filename order. Each migration file is applied in a transaction.

After migrations, seed RBAC and the first administrator as part of the controlled bootstrap process:

npm --workspace api-main run db:seed

The RBAC seed creates permissions, an administrator role with all permissions, and can assign that role to the configured initial admin user when available.

Health and API Metadata

Use the health endpoint for infrastructure readiness checks:

GET /health

Expected response shape:

{
  "status": "ok",
  "postgres": true
}

postgres: false means the API process is reachable but database connectivity is failing.

Use these metadata endpoints during deployment verification:

Endpoint	Purpose
/api/auth/.well-known/openid-configuration	Verify issuer, token endpoint, authorization endpoint, UserInfo, and JWKS metadata.
/api/auth/jwks	Verify signing key publication.
/openapi.json	Verify documented API surface is reachable.
/docs	Verify Swagger UI is reachable when exposed for operators.

Application Registration Inventory

Maintain an inventory of every registered third-party application:

Item	Why it matters
Owner/team	Needed for incident communication and scope changes.
client_id	Identifies the application in OIDC requests.
Allowed web origins	Controls browser CORS and redirect URI derivation.
Redirect paths	Controls valid authorization callbacks.
Scopes	Controls token claims and external API access.
Post-verification redirect path	Controls where users can be sent after email verification.
Logo and display name	Affects consent screen trust and user recognition.

Review application registrations regularly and remove unused origins, paths, and scopes.

Change Management

Treat these changes as security-sensitive:

• adding or removing allowed web origins
• changing redirect paths
• adding scopes such as email, permissions, or offline_access
• deleting or disabling an application
• changing RBAC permissions or role assignments
• rotating auth, encryption, database, object storage, or email-service credentials
• changing issuer, login, consent, API, or admin URLs

Recommended rollout process:

1. Test the change in sandbox or staging first.
2. Notify affected application owners.
3. Apply changes during a planned window if sessions or redirects may be affected.
4. Ask users to start a new login after scope or redirect changes.
5. Monitor 401, 403, invalid_grant, INVALID_REDIRECT_URI, and CORS errors after release.

Monitoring Signals

Track these operational signals:

Signal	Possible meaning
Increased INVALID_REDIRECT_URI	Registered origin/path mismatch or client deploying a new callback URL.
Increased CORS failures	Browser origin not registered or stale application config.
Increased invalid_grant	Reused codes, expired codes, verifier mismatch, or refresh-token issues.
Increased 401 UNAUTHORIZED on external APIs	Expired tokens, client token-storage issue, or session churn.
Increased 403 FORBIDDEN with missingScopes	Application scopes changed or integration requesting fields it is not granted.
postgres: false on /health	Database outage or connectivity/configuration issue.
Email verification failures	Email service disabled, misconfigured, or delivery provider issue.

Avoid logging token values or authorization codes while adding diagnostics.

Support Runbook

When an integration reports an authentication issue, collect non-secret diagnostics only:

• client_id
• timestamp and environment
• exact redirect URI used
• browser origin used for SPA calls
• requested scopes
• HTTP status and error code
• whether the user completed email verification
• whether the failure happened at authorize, callback, token exchange, or external API call

Never ask users or partners to send access tokens, refresh tokens, ID tokens, authorization codes, passwords, or private keys in support channels.

Deprecation and Cleanup

When removing an application or redirect:

1. Notify the application owner.
2. Remove unused scopes first where possible.
3. Remove unused redirect paths and origins.
4. Delete the application only after traffic has stopped.
5. Monitor for failed authorization and CORS attempts after cleanup.

Protected system applications may not be deletable. Treat built-in clients and admin access as platform dependencies.

Launch Readiness Checklist

• Production API, main web, and admin web URLs are reachable.
• OIDC discovery metadata reports the expected issuer and endpoints.
• JWKS endpoint is reachable.
• Database migrations and RBAC seed have completed.
• /health returns status: ok and postgres: true.
• Admin user has login-web-admin plus needed management permissions.
• Email verification has been tested end to end.
• Every production integration has exact origins, redirect paths, and least-privilege scopes.
• Browser SPA integrations have CORS tested from the production origin.
• Monitoring and support runbooks avoid collecting secrets.