Get Started
Basic Usage
Email & Password + Sessions
Standalone Mode
app_name = "Authula"
base_url = "http://localhost:8080"
base_path = "/api/auth"
# -----------------------------------
# - Database Configuration
# -----------------------------------
[database]
provider = "sqlite"
url = "auth.db"
# -----------------------------------
# - Logger Configuration
# -----------------------------------
[logger]
level = "debug"
# -----------------------------------
# - Session Configuration
# -----------------------------------
[session]
cookie_name = "authula.session_token"
expires_in = "24h"
update_age = "5m"
cookie_max_age = "24h"
secure = false
http_only = true
same_site = "lax"
auto_cleanup = true
cleanup_interval = "1m"
max_sessions_per_user = 5
# -----------------------------------
# - Verification Configuration
# -----------------------------------
[verification]
auto_cleanup = true
cleanup_interval = "1m"
# -----------------------------------
# - Security Configuration
# -----------------------------------
[security]
trusted_origins = ["http://localhost:3000"]
trusted_headers = []
trusted_proxies = []
[security.cors]
allow_credentials = true
allowed_origins = ["http://localhost:3000"]
allowed_methods = ["OPTIONS", "GET", "POST", "PUT", "PATCH", "DELETE"]
allowed_headers = ["Authorization", "Content-Type", "Set-Cookie", "Cookie"]
exposed_headers = []
max_age = "24h"
# -----------------------------------
# - Event Bus Configuration
# -----------------------------------
[event_bus]
prefix = ""
max_concurrent_handlers = 100
context_timeout = "5s"
provider = "gochannel"
[event_bus.go_channel]
buffer_size = 100
# -----------------------------------
# - Plugins Configuration
# -----------------------------------
[plugins]
# --- Email Plugin ---
[plugins.email]
enabled = true
provider = "smtp"
from_address = "noreply@example.com"
# --- Email/Password Plugin ---
[plugins.email_password]
enabled = true
min_password_length = 8
max_password_length = 128
disable_sign_up = false
require_email_verification = true
auto_sign_in = true
send_email_on_sign_up = true
send_email_on_sign_in = false
email_verification_expires_in = "24h"
password_reset_expires_in = "1h"
request_email_change_expires_in = "1h"
# --- Session Plugin ---
[plugins.session]
enabled = true
# -----------------------------------
# - Route Mappings
# -----------------------------------
# Core routes
[[route_mappings]]
paths = ["GET:/me", "POST:/sign-out"]
plugins = ["session.auth"]
# Email/Password routes
[[route_mappings]]
paths = [
"POST:/email-password/sign-in",
"POST:/email-password/sign-up",
"GET:/email-password/verify-email"
]
plugins = ["session.auth.optional"]
[[route_mappings]]
paths = [
"POST:/email-password/send-email-verification",
"POST:/email-password/request-password-reset",
"POST:/email-password/change-password",
"POST:/email-password/request-email-change",
]
plugins = ["session.auth"]Library Mode
package main
import (
"log"
"net/http"
"github.com/joho/godotenv"
authula "github.com/Authula/authula"
authulaconfig "github.com/Authula/authula/config"
authulamodels "github.com/Authula/authula/models"
emailplugin "github.com/Authula/authula/plugins/email"
emailpasswordplugin "github.com/Authula/authula/plugins/email-password"
emailpasswordplugintypes "github.com/Authula/authula/plugins/email-password/types"
emailplugintypes "github.com/Authula/authula/plugins/email/types"
sessionplugin "github.com/Authula/authula/plugins/session"
)
func main() {
_ = godotenv.Load(".env")
config := authulaconfig.NewConfig(
authulaconfig.WithAppName("YourAppName"),
authulaconfig.WithBasePath("/api/auth"),
authulaconfig.WithDatabase(authulamodels.DatabaseConfig{
Provider: "sqlite",
URL: "auth.db",
}),
authulaconfig.WithLogger(authulamodels.LoggerConfig{
Level: "debug",
}),
authulaconfig.WithSession(authulamodels.SessionConfig{
CookieName: "authula.session_token",
ExpiresIn: 24 * time.Hour,
UpdateAge: 5 * time.Minute,
CookieMaxAge: 24 * time.Hour,
Secure: false,
HttpOnly: true,
SameSite: "lax",
MaxSessionsPerUser: 5,
AutoCleanup: true,
CleanupInterval: time.Minute,
}),
authulaconfig.WithVerification(authulamodels.VerificationConfig{
AutoCleanup: true,
CleanupInterval: time.Minute,
}),
authulaconfig.WithSecurity(authulamodels.SecurityConfig{
TrustedOrigins: []string{"http://localhost:3000"},
CORS: authulamodels.CORSConfig{
AllowCredentials: true,
AllowedOrigins: []string{"http://localhost:3000"},
AllowedMethods: []string{"OPTIONS", "GET", "POST", "PATCH", "PUT", "DELETE"},
AllowedHeaders: []string{"Authorization", "Content-Type", "Set-Cookie", "Cookie"},
ExposedHeaders: []string{},
MaxAge: 24 * time.Hour,
},
}),
authulaconfig.WithEventBus(authulamodels.EventBusConfig{
Provider: authulaevents.ProviderGoChannel,
}),
authulaconfig.WithRouteMappings(
[]authulamodels.RouteMapping{
// Core routes
{
Paths: []string{"GET:/me", "POST:/sign-out"},
Plugins: []string{"session.auth"},
},
// Email/Password routes
{
Paths: []string{
"POST:/email-password/sign-in",
"POST:/email-password/sign-up",
"GET:/email-password/verify-email",
},
Plugins: []string{"session.auth.optional"},
},
{
Paths: []string{
"POST:/email-password/send-email-verification",
"POST:/email-password/request-password-reset",
"POST:/email-password/change-password",
"POST:/email-password/request-email-change",
},
Plugins: []string{"session.auth"},
},
},
),
)
auth := authula.New(&authula.AuthConfig{
Config: config,
Plugins: []authulamodels.Plugin{
emailplugin.New(emailplugintypes.EmailPluginConfig{
Enabled: true,
Provider: emailplugintypes.ProviderSMTP,
FromAddress: "email@domain.com",
}),
emailpasswordplugin.New(emailpasswordplugintypes.EmailPasswordPluginConfig{
Enabled: true,
MinPasswordLength: 8,
MaxPasswordLength: 32,
DisableSignUp: false,
RequireEmailVerification: true,
AutoSignIn: true,
SendEmailOnSignUp: true,
SendEmailOnSignIn: false,
EmailVerificationExpiresIn: 24 * time.Hour,
PasswordResetExpiresIn: time.Hour,
RequestEmailChangeExpiresIn: time.Hour,
}),
sessionplugin.New(sessionplugin.SessionPluginConfig{
Enabled: true,
}),
},
})
// Start the server and mount the handler
log.Fatal(http.ListenAndServe(":8080", auth.Handler()))
}Environment Variables
SMTP_HOST="domain.com"
SMTP_PORT="465"
SMTP_USER="username"
SMTP_PASS="password"Testing the Setup
Sign Up
curl -X POST http://localhost:8080/api/auth/email-password/sign-up \
-H "Content-Type: application/json" \
-d '{"name": "John Doe", "email": "john.doe@example.com", "password": "password123"}'Sign In
curl -X POST http://localhost:8080/api/auth/email-password/sign-in \
-H "Content-Type: application/json" \
-d '{"email": "john.doe@example.com", "password": "password123"}'Get Authenticated User Info
curl -X GET http://localhost:8080/api/auth/me \
-H "Cookie: authula.session_token=your-session-token"