Skip to content
Mindful Auth Docs (BETA)

Mindful Auth - Astro Template Overview

Official Astro template for Mindful Auth authentication integration. This Astro template provides a complete authentication portal with:

  • Server-side session validation via Astro middleware
  • Authentication proxy to Mindful Auth central API
  • Clean Astro components with minimal JavaScript
  • Hybrid static/SSR rendering for optimal performance
  • Easy deployment to Cloudflare Workers

Project Structure

Section titled “Project Structure”
my-portal/                      # Your project created from template
├── src/
│   ├── middleware.ts           # Session validation middleware (DO NOT DELETE)
│   ├── env.d.ts                # TypeScript environment definitions (DO NOT DELETE)
│   ├── styles/
│   │   └── global.css          # Global styles for all pages
│   ├── lib/
│   │   └── email.ts            # Email service (Postmark integration)
│   ├── pages/
│   │   ├── index.astro              # Root redirect to login
│   │   ├── login.astro              # Password login (DO NOT DELETE)
│   │   ├── register.astro           # Password registration (DO NOT DELETE)
│   │   ├── magic-login.astro        # Magic link login (DO NOT DELETE)
│   │   ├── magic-register.astro     # Magic link registration (DO NOT DELETE)
│   │   ├── forgot-password.astro    # Password reset request (DO NOT DELETE)
│   │   ├── resend-verification.astro # Resend email verification (DO NOT DELETE)
│   │   ├── auth/
│   │   │   └── [...slug].ts         # Auth API proxy to Mindful Auth (DO NOT DELETE)
│   │   ├── reset-password/
│   │   │   └── [...token].astro     # Password reset with token (DO NOT DELETE)
│   │   ├── email-verified/
│   │   │   └── [...params].astro    # Email verified redirect (DO NOT DELETE)
│   │   ├── verify-magic-link/
│   │   │   └── [...params].astro    # Magic link verification (DO NOT DELETE)
│   │   ├── api/
│   │   │   ├── protected-api/       # Protected API endpoints
│   │   │   └── public/
│   │   │       ├── custom-public/   # Custom public endpoints
│   │   │       └── webhooks/
│   │   │           └── mauth-webhook.ts # Mindful Auth webhook handler for Postmark implementation
│   │   └── [memberid]/
│   │       ├── index.astro          # User profile and security settings (DO NOT DELETE)
│   │       ├── dashboard.astro      # User dashboard
│   │       ├── [page]/
│   │       │   └── sample.astro     # Example dynamic route
│   │       └── static-folder/
│   │           └── static-page.astro # Example static page
│   └── layouts/
│       ├── AuthLayout.astro    # Layout for auth pages
│       └── ProtectedLayout.astro # Layout for protected pages
├── astro.config.mjs            # Astro configuration
├── wrangler.jsonc              # Cloudflare Workers configuration
├── package.json
└── tsconfig.json

Core Dependencies

Section titled “Core Dependencies”

This template includes the @mindfulauth/core npm library, which provides:

  • Session validation middleware - Validates user sessions on protected routes
  • Authentication proxy - Routes auth requests to the central Mindful Auth API
  • Type definitions - TypeScript support for Mindful Auth integration
  • Security utilities - Built-in request sanitization and validation

The library is automatically configured in src/middleware.ts and requires no additional setup for standard authentication flows.

Prerequisites

Section titled “Prerequisites”
  • Mindful Auth account with registered hostnames. Create account at https://app.mindfulauth.com/register
  • Internal API Key: Generated for your tenant (used for server-to-server validation). The INTERNAL_API_KEY must be added as a secret environment variable in your deployment platform (e.g. Cloudflare Workers).
  • Node.js 18+: Required for Astro development