Skip to Content
FrontendAppsLoginAPI Calls Documentation

API Calls Documentation

Introduction

An overview of the API calls made in the login app and their purpose.

This login application handles user authentication, password reset, two-factor authentication (2FA), OAuth authorization, and impersonation. Most of the authentication flows run as Next.js Server Actions ("use server"), not as /api/* route handlers — only a few flows (logout, OAuth authorize, status, config-login) still go through dedicated API routes.

The repo’s docs/API_Calls.md still documents an older shape of this app (/api/getAuth, /api/2fa, /api/forgot-password, /api/csrf-token, /api/clear-cache). Those routes no longer exist in the current codebase — login, 2FA, forgot password, CSRF token generation, and cache clearing were migrated to Server Actions. This page reflects the current implementation.

External API Endpoints

Google reCAPTCHA

https://www.google.com/recaptcha/api/siteverify 

  • Description: Verify reCAPTCHA tokens submitted by users.
  • Method: POST
  • Used in: verified server-side alongside login, 2fa, forgot-password, and forgot-password/reset server actions.

{tenant}.login.solidservice.link/api/check

  • Description: Authenticate user credentials and obtain access/refresh tokens.
  • Method: POST
  • Used in: src/app/actions/login.ts - loginAction()
  • Request Headers: Authorization: Basic base64(username:password)
  • Request Body:
{
  "recaptcha_token": "recaptcha_token",
  "recaptcha_version": "v3"
}
  • Returns: { token, refresh_token, refresh_token_expiration, hintWord? }

{tenant}.login.solidservice.link/api/v1/security/2fa/prepare

  • Description: Prepare a 2FA challenge (resolve which providers — TOTP, email code, WebAuthn — are available for the user).
  • Method: POST
  • Used in: src/app/[locale]/2fa/actions.ts
  • Headers: Authorization: Bearer {jwt_token} (from the currentUser cookie set by login)

{tenant}.login.solidservice.link/api/v1/security/2fa/email/resend

  • Description: Resend the one-time email code used by the email-based 2FA provider.
  • Method: POST
  • Used in: src/app/[locale]/2fa/actions.ts
  • Headers: Authorization: Bearer {jwt_token}

{tenant}.login.solidservice.link/2fa_check

  • Description: Verify the 2FA code (TOTP, email code, or backup code) and complete the login.
  • Method: POST
  • Used in: src/app/[locale]/2fa/actions.ts - verify2faAction()
  • Headers: Authorization: Bearer {jwt_token}
  • Request Body:
{
  "auth_code": "2fa_code",
  "recaptcha_token": "recaptcha_token"
}
  • Returns: New token / refresh_token pair with mfa_completed: true in the decoded JWT.

{tenant}.login.solidservice.link/reset-password

  • Description: Request a password reset email.
  • Method: POST
  • Used in: src/app/[locale]/forgot-password/actions.ts - requestForgotPasswordAction()
  • Request Body: { "email": "user@example.com", "recaptcha_token": "recaptcha_token" }
  • Note: Always returns success regardless of whether the email exists, to avoid leaking account existence.

{tenant}.login.solidservice.link/reset-password/reset

  • Description: Reset the password using the one-time reset token from the email link.
  • Method: POST
  • Used in: src/app/[locale]/forgot-password/reset/actions.ts - forgotPasswordResetAction()
  • Request Body: { "resetToken": "...", "plainPassword": "...", "recaptcha_token": "...", "recaptcha_version": "v3" }

{tenant}.login.solidservice.link/api/v1/impersonate

  • Description: SUPERADMIN-only — obtain a JWT for a target user, effectively logging the caller in as that user (no refresh token).
  • Method: POST
  • Used in: src/app/actions/impersonate.ts - impersonate()
  • Headers: Authorization: Bearer {superadmin_jwt_token}
  • Request Body: { "recaptcha_token": "...", "userIdentifier": "..." }
  • Role: Requires ROLE_SUPERADMIN. See User Roles.
  • Description: Refresh the access token using the refresh token cookie.
  • Method: POST
  • Used in: src/lib/token/RefreshToken.ts, called from /api/auth/session-refresh.

Server Actions

These are Next.js Server Actions ("use server"), called directly from client components/hooks — there is no corresponding /api/* HTTP route for them.

loginAction()

  • Location: src/app/actions/login.ts
  • Used in: src/hooks/Login/useLoginForm.tsx
  • Behavior: Validates username format, rate-limits (3 requests / 60s / IP, cooldown 30s–300s), resolves tenant, calls the login service, decodes the JWT (mfa_completed), sets auth cookies, optionally stores app-phpr-target-url.

verify2faAction()

  • Location: src/app/[locale]/2fa/actions.ts
  • Used in: src/hooks/useMfaForm.tsx
  • Behavior: Requires a valid currentUser cookie, rate-limits (3 requests / 10s / IP), calls 2fa_check, updates auth cookies on success.

requestForgotPasswordAction()

  • Location: src/app/[locale]/forgot-password/actions.ts
  • Used in: src/hooks/useForgotPasswordForm.tsx
  • Behavior: Sanitizes the email, rate-limits (3 requests / 10s / IP), calls reset-password, always returns { success: true } on a successful upstream call.

forgotPasswordResetAction()

  • Location: src/app/[locale]/forgot-password/reset/actions.ts
  • Used in: src/hooks/useForgotPasswordResetForm.tsx
  • Behavior: Validates the reset token and password strength (level ≥ 4, score ≥ 4) before calling reset-password/reset. Rate-limited (3 requests / 10s / IP).

getCsrfToken()

  • Location: src/app/actions/csrf.ts
  • Behavior: Generates a CSRF token (generateCsrfToken()), rate-limited by IP.

clearCacheAction()

  • Location: src/app/actions/clearCache.ts
  • Behavior: Clears the AppCache and ConfigCache DynamoDB tables. Rate-limited by IP.

impersonate()

  • Location: src/app/actions/impersonate.ts
  • Behavior: Verifies the caller is authenticated with ROLE_SUPERADMIN (isSuperAdmin()), then calls the impersonation endpoint and swaps in the target user’s JWT as currentUser.

Internal API Routes

Next.js API routes still used for HTTP-level concerns (redirects, OAuth, status, cross-tab session refresh).

/api/logout

  • Description: Log the user out.
  • Method: GET returns { ok: true } (no-op, kept for compatibility); POST is the real logout — validates the CSRF token, then clears auth cookies.
  • Location: src/app/api/logout/route.ts
  • Returns: { ok: true } (200) or { error: "LOGIN-LOGOUT-INVALID-CSRF" } (403) / { error: "LOGIN-LOGOUT-CLEAR-COOKIES-FAILED" } (500).
  • See Logout Implementation.

/api/config-login

  • Description: Handle configuration-based login.
  • Method: POST
  • Location: src/app/api/config-login/route.ts
  • Implementation: Delegates to configLogin() from @phpcreation/frontend-config-react-nextjs-bundle/api-functions, rate-limited.

/api/authorize

  • Description: OAuth 2.0 authorization entry point. Verifies the caller’s session; if authenticated, forwards to the login service’s /authorize endpoint, otherwise redirects to the login page and stashes the return URL in cookies (auth-return-url, auth-return-query, app-phpr-target-url).
  • Method: GET
  • Location: src/app/api/authorize/route.ts
  • Rate limiting: Yes (withApiRateLimit).

/api/auth/session-refresh

  • Description: Refresh the access/refresh token pair server-side (used to keep a session alive across tabs without a full re-login) and redirect back to next.
  • Method: GET
  • Location: src/app/api/auth/session-refresh/route.ts
  • Sets: A short-lived recently_refreshed cookie (15s) so verifyAuth doesn’t loop on a token that is still near expiry right after a refresh.

/api/auth/end-session

  • Description: Clear auth cookies and redirect to a safe next/nextUrl path.
  • Method: GET
  • Location: src/app/api/auth/end-session/route.ts

/api/auth/clear-auth-return

  • Description: Clear the OAuth return cookies (auth-return-url, auth-return-query). Exists as a route because cookie mutation isn’t allowed from Server Components.
  • Method: GET
  • Location: src/app/api/auth/clear-auth-return/route.ts

/api/error-catalog

  • Description: Return the app’s error code catalog (used by the front-end to map error codes to translated messages).
  • Method: GET
  • Location: src/app/api/error-catalog/route.ts
  • Rate limiting: Yes (withApiRateLimit, api-error-catalog).

Status Routes

/api/status

  • Description: Get basic status information.
  • Method: GET
  • Location: src/app/api/status/route.ts
  • Returns: { status: 'ok' }

/api/status/all

  • Description: Get comprehensive status information including app info, API status, configs, cache, and user token.
  • Method: GET
  • Location: src/app/api/status/all/route.ts

/api/status/api

  • Description: Get the status of the external API connection.
  • Method: GET
  • Location: src/app/api/status/api/route.ts

/api/status/configs

  • Description: Get the status of configuration services.
  • Method: GET
  • Location: src/app/api/status/configs/route.ts

/api/status/cache

  • Description: Get the status of cache tables (AppCache and ConfigCache).
  • Method: GET
  • Location: src/app/api/status/cache/route.ts

/api/status/user-token/check

  • Description: Validate and check the user token.
  • Method: GET
  • Location: src/app/api/status/user-token/check/route.ts
  • Authentication: Reads token from currentUser cookie.

/api/status/user-token/display

  • Description: Get user token display information.
  • Method: GET
  • Location: src/app/api/status/user-token/display/route.ts
  • Authentication: Reads token from currentUser cookie.

/api/status/user-token/expected

  • Description: Get expected user token information.
  • Method: GET
  • Location: src/app/api/status/user-token/expected/route.ts
Last updated on
phpreaction-frontend-login-reactImplementing the New Logout Process