API referencePlatform APIEndpoint reference
GUIDE & REFERENCE

/api/auth/refresh (dashboard)

Source-derived dashboard endpoint contract, authentication, request validation, responses, and errors.

This is the dashboard service route. Its origin and authentication are described in Platform API overview and Authentication. A path shared by another service is a different endpoint.

PropertyContract
MethodsPOST
Path/api/auth/refresh
Path parametersNone
Query parameters read in routeNone read directly; schema validation below may define additional fields
Headers read in routeNo additional direct header reads; authentication helpers may read credentials

Authentication and access

OAuth browser flow using HTTP-only l1fe_* cookies. Exchange/refresh/logout have endpoint-specific inputs and rate limits.

Method behavior

The handler excerpt preserves field validation, response envelopes, cookie changes, and exception branches. Values returned by service helpers retain their named response type above; for passthrough routes, the upstream response is authoritative.

POST

export async function POST(request: NextRequest): Promise<NextResponse> {
  // Rate limit: 20 refresh attempts per minute per IP
  const clientIp = getClientIp(request);
  if (!checkRateLimit(clientIp, 'refresh')) {
    return NextResponse.json(
      { error: 'rate_limited', error_description: 'Too many requests. Please try again later.' },
      { status: 429 }
    );
  }

  const cookieStore = await cookies();
  const refreshToken = cookieStore.get('l1fe_refresh_token')?.value;

  if (!refreshToken) {
    return NextResponse.json(
      { error: 'no_refresh_token', error_description: 'No refresh token available' },
      { status: 401 }
    );
  }

  const tokenUrl = `${SSO_URL}/v4/oauth/token`;
  const params: Record<string, string> = {
    grant_type: 'refresh_token',
    client_id: CLIENT_ID,
    refresh_token: refreshToken,
  };

  if (CLIENT_SECRET) {
    params.client_secret = CLIENT_SECRET;
  }

  try {
    const tokenResponse = await fetch(tokenUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams(params),
    });

    if (!tokenResponse.ok) {
      const errorData = await tokenResponse.json().catch(() => ({}));
      console.error('Token refresh failed:', errorData);

      // Clear invalid cookies
      const response = NextResponse.json(
        {
          error: (errorData as Record<string, string>).error || 'refresh_failed',
          error_description:
            (errorData as Record<string, string>).error_description ||
            'Token refresh failed',
        },
        { status: tokenResponse.status }
      );
      response.cookies.delete('l1fe_access_token');
      response.cookies.delete('l1fe_refresh_token');
      response.cookies.delete('l1fe_id_token');
      return response;
    }

    const tokens = await tokenResponse.json();
    const response = NextResponse.json({ refreshed: true });
    setAuthTokenCookies(response, tokens, process.env.NODE_ENV === 'production');
    return response;
  } catch (err) {
    console.error('Token refresh error:', err);
    return NextResponse.json(
      { error: 'internal_error', error_description: 'Failed to refresh token' },
      { status: 500 }
    );
  }
}

Source: minds-ui/apps/app/app/api/auth/refresh/route.ts:26.

Response and error branches

Literal HTTP statuses in the route: 401, 429, 500. Shared management error classes are defined in Errors and responses.

NextResponse.json(
      { error: 'rate_limited', error_description: 'Too many requests. Please try again later.' },
      { status: 429 }
    )

Source: minds-ui/apps/app/app/api/auth/refresh/route.ts:30.

NextResponse.json(
      { error: 'no_refresh_token', error_description: 'No refresh token available' },
      { status: 401 }
    )

Source: minds-ui/apps/app/app/api/auth/refresh/route.ts:40.

tokenResponse.json()

Source: minds-ui/apps/app/app/api/auth/refresh/route.ts:65.

NextResponse.json(
        {
          error: (errorData as Record<string, string>).error || 'refresh_failed',
          error_description:
            (errorData as Record<string, string>).error_description ||
            'Token refresh failed',
        },
        { status: tokenResponse.status }
      )

Source: minds-ui/apps/app/app/api/auth/refresh/route.ts:69.

tokenResponse.json()

Source: minds-ui/apps/app/app/api/auth/refresh/route.ts:84.

NextResponse.json({ refreshed: true })

Source: minds-ui/apps/app/app/api/auth/refresh/route.ts:85.

NextResponse.json(
      { error: 'internal_error', error_description: 'Failed to refresh token' },
      { status: 500 }
    )

Source: minds-ui/apps/app/app/api/auth/refresh/route.ts:90.

Evidence

Generated from the local source snapshot on 2026-09-12. This page documents implemented code and does not certify a deployed service, permissions configuration, or successful provider operation.

Source file: minds-ui/apps/app/app/api/auth/refresh/route.ts. SHA-256: cf67eacafc8ec93e94e86e5e549be245d2e57c0de5d1534f0457700f6163963e.

On this page