Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ricardomb-tech/auth-service/llms.txt

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

Auth Service is configured entirely via environment variables — there are no hardcoded values anywhere in the codebase. Every sensitive credential, infrastructure address, and behavioral toggle is injected at runtime through the environment. In the prod Spring profile there are no fallback defaults: if a required variable is absent or blank, the application context will refuse to start, making misconfiguration impossible to overlook in production.

​
Variable Groups

​
Database

Auth Service connects to a PostgreSQL 15 database. All five variables are required in every profile.
​
DB_HOST
string
required
Hostname or IP address of the PostgreSQL server.Example: localhost
​
DB_PORT
integer
required
TCP port the PostgreSQL server listens on.Example: 5432
​
DB_NAME
string
required
Name of the PostgreSQL database.Example: auth_service
​
DB_USER
string
required
PostgreSQL username used to connect.Example: auth_service
​
DB_PASSWORD
string
required
Password for the PostgreSQL user.Example: auth_service (change in any non-local environment)

​
JWT

Auth Service signs JWT access tokens with HS256 using a pair of secrets — one active, one previous — to support zero-downtime secret rotation. See JWT Tokens for the full rotation procedure.
​
JWT_SECRET_CURRENT
string
required
The active signing secret. New tokens are always signed with this key; incoming tokens are validated against it first.Must be a Base64-encoded random value of at least 256 bits (32 bytes). Generate one with:
openssl rand -base64 32
​
JWT_SECRET_PREVIOUS
string
The previous signing secret, used only for validation during a rolling key rotation. Leave blank (or omit) when not actively rotating.Default: (empty — rotation inactive)

​
OAuth2

Social login credentials and the frontend redirect targets for the OAuth2 callback flow. All six variables are required when OAuth2 login is enabled.
​
GOOGLE_CLIENT_ID
string
required
OAuth2 Client ID obtained from the Google Cloud Console.
​
GOOGLE_CLIENT_SECRET
string
required
OAuth2 Client Secret obtained from the Google Cloud Console.
​
GITHUB_CLIENT_ID
string
required
OAuth App Client ID from GitHub Settings → Developer settings → OAuth Apps.
​
GITHUB_CLIENT_SECRET
string
required
OAuth App Client Secret from GitHub Settings.
​
OAUTH2_SUCCESS_REDIRECT_URI
string
required
The frontend URL to which the browser is redirected after a successful OAuth2 login. A short-lived, one-time exchange code is appended as a query parameter — not the JWT itself. The frontend must call POST /auth/oauth2/exchange to redeem that code for the actual token pair.Example: http://localhost:3000/oauth2/success
​
OAUTH2_FAILURE_REDIRECT_URI
string
required
The frontend URL to which the browser is redirected when OAuth2 login fails (provider error, unverified email, etc.).Example: http://localhost:3000/oauth2/failure

​
Admin

Initial administrator account provisioned at startup (Epic 4). Both variables must be set together.
​
AUTH_ADMIN_EMAIL
string
required
Email address for the initial admin account.
​
AUTH_ADMIN_PASSWORD
string
required
Password for the initial admin account. Use a strong, randomly generated value in all non-local environments.

​
Email

Auth Service sends transactional emails (account verification, password reset) via SMTP. In development, MailHog — included in docker-compose.yml — captures all outgoing mail so nothing reaches real inboxes.
​
MAIL_HOST
string
required
Hostname of the SMTP server.Dev default: localhost (MailHog)
​
MAIL_PORT
integer
required
SMTP port.Dev default: 1025 (MailHog)

​
Messaging

Auth Service publishes domain events to a Kafka-compatible broker (Redpanda in development). The broker is already running via docker-compose.yml; event consumption is implemented in Epic 6.
​
KAFKA_BOOTSTRAP_SERVERS
string
required
Comma-separated list of Kafka/Redpanda bootstrap server addresses.Example: localhost:9092

​
App

​
APP_BASE_URL
string
required
The public base URL of the Auth Service itself. Used to construct links in outgoing emails (e.g. the account verification link).Example: http://localhost:8080

​
Complete .env Example

Copy .env.example to .env and fill in your values before starting the service. 
cp .env.example .env

# ===============================
# DATABASE
# ===============================
DB_HOST=localhost
DB_PORT=5432
DB_NAME=auth_service
DB_USER=auth_service
DB_PASSWORD=auth_service

# ===============================
# JWT (active + previous pair for zero-downtime rotation)
# ===============================
JWT_SECRET_CURRENT=change-me-to-a-256-bit-random-secret
JWT_SECRET_PREVIOUS=

# ===============================
# OAUTH2 (Google + GitHub federated login)
# ===============================
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
OAUTH2_SUCCESS_REDIRECT_URI=http://localhost:3000/oauth2/success
OAUTH2_FAILURE_REDIRECT_URI=http://localhost:3000/oauth2/failure

# ===============================
# ADMIN INITIAL ACCOUNT
# ===============================
AUTH_ADMIN_EMAIL=
AUTH_ADMIN_PASSWORD=

# ===============================
# EMAIL (dev: MailHog from docker-compose.yml)
# ===============================
MAIL_HOST=localhost
MAIL_PORT=1025

# ===============================
# DOMAIN EVENTS (Redpanda from docker-compose.yml)
# ===============================
KAFKA_BOOTSTRAP_SERVERS=localhost:9092

# ===============================
# APP
# ===============================
APP_BASE_URL=http://localhost:8080
Never commit a .env file containing real secrets to version control. The .env file is listed in .gitignore for this reason. Use a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault, or your CI/CD platform’s secret store) to inject values in non-local environments.
The prod Spring profile (application-prod.properties) declares no default values for any variable. If a required environment variable is missing or blank when the service starts, Spring Boot’s configuration binding will throw an IllegalStateException and abort startup immediately — rather than silently using an empty or insecure value.

Build docs developers (and LLMs) love

Get started for freeTalk to us