MonSPHERE

API & Auth

Authentication

JWT sessions, API keys, MFA/TOTP, and the OAuth provider catalog.

MonSPHERE supports two authentication schemes on the same API, handled by one shared middleware.

JWT (user sessions)

POST /api/v1/auth/login returns a short-lived access token and a refresh token. Send the access token as Authorization: Bearer <token>. Refresh via POST /api/v1/auth/refresh before expiry.

API Keys (service-to-service)

Organization-scoped keys authenticate via a dedicated X-Api-Key header — not Authorization. Create, rotate, and revoke keys under /api/v1/organizations/:orgId/api-keys. API keys are independently rate limited (see Rate Limits).

Multi-Factor Authentication

MFA is real RFC 6238 TOTP, not a mocked toggle:

curl -X POST https://api.monsphere.com/api/v1/auth/mfa/setup -H "Authorization: Bearer $ACCESS_TOKEN"
# returns { secret, provisioningUri, qrCodePngBase64 }

curl -X POST https://api.monsphere.com/api/v1/auth/mfa/confirm \
  -H "Authorization: Bearer $ACCESS_TOKEN" -d '{"code": "123456"}'
# returns 10 single-use backup codes, shown once

Once enabled, POST /auth/login returns a 5-minute challenge token instead of real tokens; redeem it at POST /api/v1/auth/mfa/verify with a TOTP code or backup code.

OAuth providers

A real OAuth provider catalog exists (GitHub, GitLab, Google, Microsoft, Slack) for organization-level SSO configuration. GitHub is live-configurable via environment variables today; the others are real catalog rows not yet enabled by default — check the Roadmap before building against a provider that isn't live yet.

Password reset & email verification

/auth/forgot-password, /auth/reset-password, /auth/verify-email, and /auth/resend-verification round out the real, non-mocked auth flow — all send real email through the platform's mailer.