Authentication (SSO)
The single sign-on entry point and the browser session endpoints. The recommended way to log members in.
SSO-aware entry point (/auth/sso/authorize) and the cookie-backed browser endpoints (/auth/sso/session, /auth/sso/sessions, /auth/sso/logout). After a member logs in once via Discord, every subsequent project login on the same browser skips the Discord screen. Recommended default for new integrations.
Initiate authorization request (SSO-aware - recommended)
/api/auth/sso/authorizeRecommended default for new "Login with MicroClub" buttons. Same query contract as GET /auth/authorize. If the caller has a valid mcdi_sso cookie, the Discord OAuth bounce is skipped and the browser is redirected straight to the platform's redirect_uri with ?code=...&state=.... Otherwise this falls back to the existing /auth/authorize flow (Discord OAuth).
Use GET /auth/authorize instead when you need to force a fresh Discord consent.
Authentication: None, this endpoint is public.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
client_id | query | string (uuid) | yes | Project ID (UUID) identifying the client application |
redirect_uri | query | string | yes | URI to redirect back to after authentication. Must be whitelisted for the project. |
server_id | query | string | yes | Discord server ID to verify membership against |
state | query | string | yes | Opaque state value passed through to the redirect. Use for CSRF protection. |
Responses
| Status | Description | Body |
|---|---|---|
200 | object | |
302 | Redirects either to Discord OAuth (no SSO yet) or back to the platform with a fresh callback code (SSO hit). |
Open in Swagger (opens in a new tab)
Destroy the global SSO session (log out everywhere)
/api/auth/sso/logoutReads the mcdi_sso httpOnly cookie, destroys the SSO session, cascades to every project session for the same member, and clears the cookie. Idempotent - succeeds even if the cookie is missing.
Authentication: None, this endpoint is public.
Responses
| Status | Description | Body |
|---|---|---|
204 | SSO session destroyed and cookie cleared. |
Open in Swagger (opens in a new tab)
Get current SSO session status
/api/auth/sso/sessionReads the mcdi_sso httpOnly cookie set after Discord login and returns the authenticated member. Returns 401 with { authenticated: false } when the cookie is missing or expired.
Authentication: None, this endpoint is public.
Responses
| Status | Description | Body |
|---|---|---|
200 | SsoSessionStatusDto | |
401 | SsoSessionUnauthenticatedDto |
Open in Swagger (opens in a new tab)
List active project sessions under the current SSO session
/api/auth/sso/sessionsReturns one entry per active (non-expired) project session for the member identified by the mcdi_sso cookie. Token material is never returned. Returns 401 when the SSO cookie is missing or expired.
Authentication: None, this endpoint is public.
Responses
| Status | Description | Body |
|---|---|---|
200 | SsoProjectSessionListDto | |
401 | Missing or expired SSO cookie. |
Open in Swagger (opens in a new tab)
Schemas
SsoMemberDto schema
| Field | Type | Required | Description |
|---|---|---|---|
avatar | string or null | no | |
discordId | string | yes | Discord user ID (same as id in MCDI) |
id | string | yes | |
username | string | yes |
SsoProjectSessionDto schema
| Field | Type | Required | Description |
|---|---|---|---|
createdAt | string (date-time) | yes | |
expiresAt | string (date-time) | yes | |
lastUsedAt | string (date-time) or null | no | Last time this project session was used. Not currently tracked on sessions, so returns createdAt as a best-effort fallback. |
projectId | string | yes | |
projectName | string | yes | |
serverId | string or null | no |
SsoProjectSessionListDto schema
| Field | Type | Required | Description |
|---|---|---|---|
sessions | array of SsoProjectSessionDto | yes |
SsoSessionStatusDto schema
| Field | Type | Required | Description |
|---|---|---|---|
authenticated | boolean | yes | |
expiresAt | string (date-time) | yes | |
member | SsoMemberDto | yes |
SsoSessionUnauthenticatedDto schema
| Field | Type | Required | Description |
|---|---|---|---|
authenticated | boolean | yes |
Source: apps/api/openapi.json.