Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/eggarcia98/auth-backend/llms.txt

Use this file to discover all available pages before exploring further.

Auth Backend is configured entirely through environment variables. Copy .env.example to .env and fill in the values before starting the server. 
cp .env.example .env
The server validates all required variables at startup using Zod. If any required variable is missing or invalid, the process exits with a descriptive error.

​
Server

​
ENVIRONMENT
string
default:"development"
The runtime environment. Accepted values are development, staging, or production. Controls logging behavior and other environment-specific settings.
​
PORT
number
default:"8080"
The port the HTTP server listens on. When deploying to Cloud Run or Docker, the container binds to 0.0.0.0 on this port.
​
FRONTEND_URL
string
required
The origin URL of your frontend application (e.g. http://localhost:3000 or https://app.example.com). This value is used to configure CORS — only requests from this origin are accepted. It is also used as the redirect destination for OAuth and password reset flows.
FRONTEND_URL=http://localhost:3000

​
Supabase

Auth Backend uses Supabase for user management and authentication. You need a Supabase project before you can run the server. To create a Supabase project:
  1. Go to supabase.com and sign in.
  2. Click New project and enter a name and password.
  3. Wait for the project to provision, then go to Project Settings → API.
  4. Copy the three values below into your .env.
​
SUPABASE_URL
string
required
Your Supabase project URL. Found under Project Settings → API → Project URL.
SUPABASE_URL=https://xxxxxxxxxxxxx.supabase.co
​
SUPABASE_ANON_KEY
string
required
The public anonymous key for your Supabase project. Found under Project Settings → API → Project API keys → anon public.This key is safe to use in server-side code and is used for unauthenticated operations.
SUPABASE_ANON_KEY=your-anon-key-here
​
SUPABASE_SERVICE_ROLE_KEY
string
required
The service role key for your Supabase project. Found under Project Settings → API → Project API keys → service_role.This key bypasses Row Level Security and is used for admin operations such as creating and managing users.
Never expose the service_role key in client-side code, public repositories, or logs. Treat it as a secret credential.
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here

​
JWT

​
JWT_SECRET
string
required
A secret key used to sign and verify JWTs. Must be at least 32 characters long.Generate a secure value with:
openssl rand -base64 32

JWT_SECRET=your-super-secret-jwt-key-min-32-chars
Use a randomly generated value of 32 or more characters. Avoid reusing this value across environments.

​
OAuth providers (optional)

OAuth credentials are optional. Omit these variables if you do not need Google or Apple Sign-In.

​
Google

Google Sign-In credentials are configured directly in Supabase, not in the backend’s environment variables. The backend uses Supabase’s OAuth abstraction — no Google credentials are needed in your .env file. To set up Google Sign-In:
  1. Go to the Google Cloud Console → APIs & Services → Credentials.
  2. Click Create credentials → OAuth client ID (application type: Web application).
  3. Add the Supabase callback URL to Authorized redirect URIs: 
    https://<your-project>.supabase.co/auth/v1/callback
  4. Copy the Client ID and Client Secret.
  5. In your Supabase dashboard, go to Authentication → Providers → Google, enable it, and paste the credentials.
No Google environment variables are required in the backend .env file. All OAuth credentials are stored and managed by Supabase.

​
Apple

To enable Apple Sign-In, you need an Apple Developer account and a Services ID.
Apple Sign-In requires a registered domain and an HTTPS callback URL. It cannot be tested on localhost without a tunnel such as ngrok.
​
APPLE_CLIENT_ID
string
Your Apple Services ID (e.g. com.example.app.service).
APPLE_CLIENT_ID=your-apple-services-id
​
APPLE_TEAM_ID
string
Your 10-character Apple Team ID. Found in the Apple Developer portal under Membership.
APPLE_TEAM_ID=XXXXXXXXXX
​
APPLE_KEY_ID
string
The key identifier for your Apple Sign-In private key. Found under Certificates, Identifiers & Profiles → Keys.
APPLE_KEY_ID=XXXXXXXXXX
​
APPLE_PRIVATE_KEY
string
The contents of the .p8 private key file downloaded from the Apple Developer portal. Include the full key including the header and footer lines.
APPLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIGH...\n-----END PRIVATE KEY-----"

​
CORS and cookies

​
CORS

CORS is configured automatically using the FRONTEND_URL variable. The server allows requests from that origin with credentials and supports the following methods: GET, POST, PUT, DELETE, and OPTIONS. To allow multiple origins or a wildcard, you would need to modify the CORS configuration in src/app.ts:
src/app.ts
await fastify.register(cors, {
  origin: config.env.FRONTEND_URL, // Change to an array or regex for multiple origins
  credentials: true,
  methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
});

​
Cookies

Access and refresh tokens are stored as HTTP-only cookies. These cookies are set automatically on login and cleared on logout. They are not accessible from JavaScript, which prevents XSS-based token theft.
CookieDescription
accessTokenShort-lived JWT used to authenticate requests.
refreshTokenLong-lived token used to obtain a new access token via POST /api/v1/auth/refresh.
When making requests from a browser, include credentials: 'include' in your fetch options so cookies are sent with cross-origin requests.

Build docs developers (and LLMs) love

Get started for freeTalk to us