App Logo
Get Started

Basic Usage

Email & Password + Sessions

Standalone Mode

config.toml
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

main.go
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

.env
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"

On this page