API Routes Reference

Internal API endpoints in the Refresh App Web application.

Authentication Endpoints

POST /auth/signin/google

OAuth sign-in with Google.

Handler: Auth.js Authentication: None (public)

Response: Redirects to Google OAuth consent screen

POST /auth/signin/microsoft

OAuth sign-in with Microsoft Entra ID.

Handler: Auth.js Authentication: None (public)

Response: Redirects to Microsoft OAuth consent screen

POST /auth/callback/google

OAuth callback from Google.

Handler: Auth.js Authentication: None (public, validated via OAuth state)

Response: Sets session cookie, redirects to /app

POST /auth/callback/microsoft

OAuth callback from Microsoft.

Handler: Auth.js Authentication: None (public, validated via OAuth state)

Response: Sets session cookie, redirects to /app

POST /auth/signout

Sign out current user.

Handler: Auth.js Authentication: Required

Response: Clears session cookie, redirects to /auth

Session Management

POST /api/session/set-active-tenant

Switch active tenant for current user.

Location: src/routes/api/session/set-active-tenant/+server.ts

Authentication: Required

Request Body:

{
	"tenantId": "tenant-id-uuid"
}

Response:

{
	"success": true
}

Side Effects:

• Sets activeTenantId cookie

• Next request will rebuild session with new tenant context

JWKS Endpoint

GET /api/jwks_json

Public JWKS endpoint for Neon RLS JWT verification. Returns RSA public key.

Authentication: None (public) Headers: CORS enabled, 1hr cache

See Architecture: Authentication Flow.

Image Management

GET /api/images

Get presigned URL for image download from R2.

Location: src/routes/api/images/+server.ts

Authentication: Required

Query Parameters:

• key: Object key in R2 bucket

Response:

{
	"url": "https://r2-bucket-url/object-key?signature=..."
}

POST /api/images/upload

Get presigned URL for image upload to R2.

Location: src/routes/api/images/upload/+server.ts

Authentication: Required

Request Body:

{
	"key": "tenant-id/filename.png",
	"contentType": "image/png"
}

Response:

{
	"url": "https://r2-bucket-url/object-key?signature=...",
	"key": "tenant-id/filename.png"
}

Usage:

// Get presigned URL
const response = await fetch('/api/images/upload', {
	method: 'POST',
	headers: { 'Content-Type': 'application/json' },
	body: JSON.stringify({
		key: `${tenantId}/logo.png`,
		contentType: file.type
	})
});

const { url, key } = await response.json();

// Upload file to R2
await fetch(url, {
	method: 'PUT',
	body: file,
	headers: { 'Content-Type': file.type }
});

Error Responses

All API endpoints return consistent error responses:

{
	"error": "Error message",
	"code": "ERROR_CODE"
}

Common Status Codes:

• 400 - Bad Request (invalid input)

• 401 - Unauthorized (not authenticated)

• 403 - Forbidden (insufficient permissions)

• 404 - Not Found

• 500 - Internal Server Error

CORS Policy

API Routes: Allow cross-origin requests

Headers:

• Access-Control-Allow-Origin: *

• Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, HEAD

• Access-Control-Allow-Headers: Content-Type, Authorization

Protected Routes: Require authentication regardless of CORS

Rate Limiting

Cloudflare Automatic:

• DDoS protection

• Suspicious traffic challenges

Application-Level: Not currently implemented

Future Enhancement:

• Per-user rate limiting

• API key rate limiting

Related Documentation

• Authentication Guide

• Security Architecture

---

Last updated: October 2025