LynCareOS (1.0.0)

Register a new user account.

Invite-only: all registrations require a valid invite_token. Self-service signup without an invite returns 403.

Invited path: creates the user with status='pending', links them to the inviting tenant as role='member'/status='invited', marks the invite as used, and returns a JWT. The user is redirected to /pending in the frontend until an admin approves them from Settings → Users.

Duplicate username or email raises 409.

Authenticate with username/email + password and return a JWT pair.

Accepts either username or email as the identifier (case-insensitive). Raises 401 for missing users or wrong passwords (same message to avoid username enumeration). Raises 403 for rejected or still-pending accounts. Updates last_login on success. Super admin users are assigned their primary tenant context if they have one; non-super users get their first active tenant membership.

Sign in or register via Google OAuth (id_token / GIS button flow).

Verifies the Google ID token credential returned by the GIS Sign-In button, then delegates all user find/create/invite logic to process_google_user. Kept for backward compatibility; new clients use POST /google/token.

Sign in or register via Google OAuth (access_token / useGoogleLogin flow).

Accepts the OAuth2 access_token returned by @react-oauth/google's useGoogleLogin hook (implicit flow, scope: openid email profile).

This endpoint exists to support the native-button Google sign-in flow on the frontend, which was introduced to fix a blank-screen bug on iOS Safari. The GIS iframe button (used by GoogleLogin component) opens a popup from within a cross-origin iframe; iOS Safari's popup blocker silently kills it. A native HTML button calling useGoogleLogin() is a first-party user gesture and is not subject to that restriction.

Validates the access_token via Google's tokeninfo + userinfo endpoints, then delegates to the same process_google_user service as the id_token flow.

Exchange a refresh token for a new access + refresh token pair.

The refresh token is read from the HttpOnly lyncare_refresh cookie (preferred) or — for backward compatibility — from the JSON body. Validates the token type, looks up the user, and re-issues both tokens. Raises 401 for an invalid/expired token or missing user; 403 if the user's account is no longer 'approved'. Token rotation means each refresh token is single-use in practice (the old token is not explicitly revoked, but the client replaces it).

List all tenants the user belongs to — for the tenant chooser UI.

Re-issue JWT pair with tid set to the selected tenant (REQ-AUTH-13).

Clear the refresh cookie and denylist any presented refresh token.

Issue a short-lived (30 s) single-use ticket for SSE connections.

The browser EventSource API cannot set custom HTTP headers, so a raw JWT in a ?token= query parameter would appear in server logs and browser history. This endpoint allows the frontend to exchange its JWT (passed via the standard Authorization header in this request) for an opaque UUID ticket that is safe to use as a query parameter.

Flow:

1. Frontend calls POST /api/auth/sse-ticket with Authorization: Bearer
2. Frontend opens EventSource('/api/.../events?ticket=')
3. Backend validates and consumes the ticket before streaming

Tickets expire after 30 seconds and can only be used once.

Return the full profile of the currently authenticated user.

Includes tenant context (tenant_id, tenant_role, tenant details) so the frontend can derive routing and access-guard decisions from a single call. Called by the frontend on app load to restore session state. Does not require 'approved' status — pending users can call this to see their own status (used by the /pending page to detect approval).

Update the authenticated user's profile fields.

PATCH semantics — only supplied fields are updated. Username and email changes require current_password verification for password accounts. Raises 409 if the new username or email is already taken. When profile_colour is changed, the update is propagated to care_group_members.display_colour for every group the user belongs to, keeping the calendar consistent without a separate sync call. Raises 400 if no updateable fields are supplied.

Set or change the user's own password, clearing the forced-reset flag.

When the account already has a password hash, current_password must match. This allows Google users to add a password without a current_password check (current_password defaults to "" and is only required when ph is non-null). On success, must_change_password is set to 0, allowing accounts that were reset by an admin to proceed normally after the first password change.

Generate a new TOTP secret and return the QR code for enrolment.

Only call this for native password-login users (no Google OAuth). MFA is not enabled until the user verifies with a code via POST /me/mfa/enable. Calling this endpoint again replaces any pending (unverified) secret.

Verify the first TOTP code and mark MFA as enabled.

Requires that POST /me/mfa/setup was called first. Once verified, all subsequent logins require a TOTP code in addition to the password. Also generates and returns one-time backup recovery codes.

Disable MFA after verifying the current TOTP code.

The user must supply a valid TOTP code (or a backup code) to prevent a third party from disabling MFA if they gain access to the session.

Verify a TOTP code during the login MFA step.

Called after initial password verification when mfa_enabled=true. The frontend should present this form when the login response includes {"mfa_required": true} in the payload. On success returns the normal auth response (access + refresh tokens).

Rate limited to 5 attempts per minute per user/IP to prevent brute-force.

Register a new user account.

Invite-only: all registrations require a valid invite_token. Self-service signup without an invite returns 403.

Invited path: creates the user with status='pending', links them to the inviting tenant as role='member'/status='invited', marks the invite as used, and returns a JWT. The user is redirected to /pending in the frontend until an admin approves them from Settings → Users.

Duplicate username or email raises 409.

Authenticate with username/email + password and return a JWT pair.

Accepts either username or email as the identifier (case-insensitive). Raises 401 for missing users or wrong passwords (same message to avoid username enumeration). Raises 403 for rejected or still-pending accounts. Updates last_login on success. Super admin users are assigned their primary tenant context if they have one; non-super users get their first active tenant membership.

Sign in or register via Google OAuth (id_token / GIS button flow).

Verifies the Google ID token credential returned by the GIS Sign-In button, then delegates all user find/create/invite logic to process_google_user. Kept for backward compatibility; new clients use POST /google/token.

Sign in or register via Google OAuth (access_token / useGoogleLogin flow).

Accepts the OAuth2 access_token returned by @react-oauth/google's useGoogleLogin hook (implicit flow, scope: openid email profile).

This endpoint exists to support the native-button Google sign-in flow on the frontend, which was introduced to fix a blank-screen bug on iOS Safari. The GIS iframe button (used by GoogleLogin component) opens a popup from within a cross-origin iframe; iOS Safari's popup blocker silently kills it. A native HTML button calling useGoogleLogin() is a first-party user gesture and is not subject to that restriction.

Validates the access_token via Google's tokeninfo + userinfo endpoints, then delegates to the same process_google_user service as the id_token flow.

Exchange a refresh token for a new access + refresh token pair.

The refresh token is read from the HttpOnly lyncare_refresh cookie (preferred) or — for backward compatibility — from the JSON body. Validates the token type, looks up the user, and re-issues both tokens. Raises 401 for an invalid/expired token or missing user; 403 if the user's account is no longer 'approved'. Token rotation means each refresh token is single-use in practice (the old token is not explicitly revoked, but the client replaces it).

List all tenants the user belongs to — for the tenant chooser UI.

Re-issue JWT pair with tid set to the selected tenant (REQ-AUTH-13).

Clear the refresh cookie and denylist any presented refresh token.

Issue a short-lived (30 s) single-use ticket for SSE connections.

The browser EventSource API cannot set custom HTTP headers, so a raw JWT in a ?token= query parameter would appear in server logs and browser history. This endpoint allows the frontend to exchange its JWT (passed via the standard Authorization header in this request) for an opaque UUID ticket that is safe to use as a query parameter.

Flow:

1. Frontend calls POST /api/auth/sse-ticket with Authorization: Bearer
2. Frontend opens EventSource('/api/.../events?ticket=')
3. Backend validates and consumes the ticket before streaming

Tickets expire after 30 seconds and can only be used once.

Return the full profile of the currently authenticated user.

Includes tenant context (tenant_id, tenant_role, tenant details) so the frontend can derive routing and access-guard decisions from a single call. Called by the frontend on app load to restore session state. Does not require 'approved' status — pending users can call this to see their own status (used by the /pending page to detect approval).

Update the authenticated user's profile fields.

PATCH semantics — only supplied fields are updated. Username and email changes require current_password verification for password accounts. Raises 409 if the new username or email is already taken. When profile_colour is changed, the update is propagated to care_group_members.display_colour for every group the user belongs to, keeping the calendar consistent without a separate sync call. Raises 400 if no updateable fields are supplied.

Set or change the user's own password, clearing the forced-reset flag.

When the account already has a password hash, current_password must match. This allows Google users to add a password without a current_password check (current_password defaults to "" and is only required when ph is non-null). On success, must_change_password is set to 0, allowing accounts that were reset by an admin to proceed normally after the first password change.

Generate a new TOTP secret and return the QR code for enrolment.

Only call this for native password-login users (no Google OAuth). MFA is not enabled until the user verifies with a code via POST /me/mfa/enable. Calling this endpoint again replaces any pending (unverified) secret.

Verify the first TOTP code and mark MFA as enabled.

Requires that POST /me/mfa/setup was called first. Once verified, all subsequent logins require a TOTP code in addition to the password. Also generates and returns one-time backup recovery codes.

Disable MFA after verifying the current TOTP code.

The user must supply a valid TOTP code (or a backup code) to prevent a third party from disabling MFA if they gain access to the session.

Verify a TOTP code during the login MFA step.

Called after initial password verification when mfa_enabled=true. The frontend should present this form when the login response includes {"mfa_required": true} in the payload. On success returns the normal auth response (access + refresh tokens).

Rate limited to 5 attempts per minute per user/IP to prevent brute-force.

Return module access status for a specific tenant member.

Returns one entry per product module (see MODULES). enabled is True unless overridden to False in tenant_user_module_access. tenant_active is True when this tenant's subscription for that module is active or trial (admins can then grant or deny member access; denying only applies once the module is active for the account).

Enable or disable a module for a specific tenant member.

Admins and super-admins cannot be restricted (their access is always full).