route-map

name	route-map
description	Complete HTTP route structure with auth layers, middleware chains, rate limiting, and handler mappings for all API and GUI endpoints.
license	MIT

Route Architecture

All routes are defined in cmd/api/main.go. The server uses Gin with these global middleware applied to all routes:

1. middleware.SecurityHeadersMiddleware() -- CSP, HSTS, X-Frame-Options
2. middleware.CORSMiddleware() -- CORS headers
3. middleware.AppIDMiddleware() -- Extracts X-App-ID header (skips /swagger, /admin, /gui)

Authentication Layers (4 systems)

Layer	Mechanism	Header/Cookie	Middleware	Scope
User Auth	JWT Bearer	Authorization: Bearer <token>	AuthMiddleware()	End-user API routes
Admin API Key	API key	X-Admin-API-Key	AdminAuthMiddleware(adminRepo)	/admin/* JSON API
App API Key	API key	X-App-API-Key + X-App-ID	AppApiKeyMiddleware(adminRepo)	/app/:id/* routes
Admin GUI Session	HTTP-only cookie	admin_session cookie	GUIAuthMiddleware(accountService)	/gui/* HTML interface

Public Routes (no auth, rate limited)

POST /register                    -> userHandler.Register           [APIRegisterRateLimit: 3/min]
POST /login                       -> userHandler.Login              [APILoginRateLimit: 5/min, lockout 10->15min]
POST /refresh-token               -> userHandler.RefreshToken       [APIRefreshTokenRateLimit: 10/min]
POST /forgot-password             -> userHandler.ForgotPassword     [APIForgotPasswordRateLimit: 3/min]
POST /reset-password              -> userHandler.ResetPassword      [APIResetPasswordRateLimit: 5/min]
GET  /verify-email                -> userHandler.VerifyEmail
POST /resend-verification         -> userHandler.ResendVerification [APIResendVerificationRateLimit: 3/min]

POST /2fa/login-verify            -> twofaHandler.VerifyLogin       [API2FAVerifyRateLimit: 5/min, lockout 10->15min]
POST /2fa/email/resend            -> twofaHandler.ResendEmail2FACode [API2FAVerifyRateLimit]
POST /2fa/sms/resend              -> twofaHandler.ResendSMS2FACode  [API2FAVerifyRateLimit]
POST /2fa/backup-email/resend     -> twofaHandler.ResendBackupEmail2FACode [API2FAVerifyRateLimit]
GET  /2fa/backup-email/verify     -> twofaHandler.VerifyBackupEmail
GET  /2fa/methods                 -> twofaHandler.GetAvailableMethods

POST /2fa/passkey/begin           -> webauthnHandler.BeginPasskey2FA    [APIPasskey2FARateLimit: 10/min]
POST /2fa/passkey/finish          -> webauthnHandler.FinishPasskey2FA   [APIPasskey2FARateLimit]

POST /passkey/login/begin         -> webauthnHandler.BeginPasswordlessLogin  [APIPasskeyLoginRateLimit: 10/min]
POST /passkey/login/finish        -> webauthnHandler.FinishPasswordlessLogin [APIPasskeyLoginRateLimit]

POST /magic-link/request          -> userHandler.RequestMagicLink    [APIMagicLinkRateLimit: 5/15min]
POST /magic-link/verify           -> userHandler.VerifyMagicLink     [APIMagicLinkRateLimit]

GET  /health                      -> healthHandler.Health             (no auth)
GET  /app-config/:app_id          -> adminHandler.GetAppLoginConfig   (no auth)

Social OAuth2 Routes (public, no rate limit)

GET /auth/google/login            -> socialHandler.GoogleLogin
GET /auth/google/callback         -> socialHandler.GoogleCallback
GET /auth/facebook/login          -> socialHandler.FacebookLogin
GET /auth/facebook/callback       -> socialHandler.FacebookCallback
GET /auth/github/login            -> socialHandler.GithubLogin
GET /auth/github/callback         -> socialHandler.GithubCallback

# Account linking callbacks (public -- user ID in OAuth state param)
GET /auth/google/link/callback    -> socialHandler.GoogleLinkCallback
GET /auth/facebook/link/callback  -> socialHandler.FacebookLinkCallback
GET /auth/github/link/callback    -> socialHandler.GithubLinkCallback

Account Linking Routes (JWT auth required)

GET /auth/google/link             -> socialHandler.GoogleLink       [AuthMiddleware]
GET /auth/facebook/link           -> socialHandler.FacebookLink     [AuthMiddleware]
GET /auth/github/link             -> socialHandler.GithubLink       [AuthMiddleware]

Protected User Routes (JWT auth + RBAC permissions)

All routes use AuthMiddleware(). RBAC permissions shown as resource:action.

# Profile (user:read, user:write, user:delete)
GET    /profile                   -> userHandler.GetProfile         [user:read]
PUT    /profile                   -> userHandler.UpdateProfile      [user:write]
DELETE /profile                   -> userHandler.DeleteAccount      [user:delete]
PUT    /profile/email             -> userHandler.UpdateEmail        [user:write]
PUT    /profile/password          -> userHandler.UpdatePassword     [user:write]

# Social accounts (user:read, user:write)
GET    /profile/social-accounts   -> socialHandler.ListSocialAccounts   [user:read]
DELETE /profile/social-accounts/:id -> socialHandler.UnlinkSocialAccount [user:write]

# Auth (no extra permission)
GET  /auth/validate               -> userHandler.ValidateToken
POST /logout                      -> userHandler.Logout

# 2FA management (settings:write, settings:read)
POST /2fa/generate                -> twofaHandler.Generate2FA       [settings:write]
POST /2fa/verify-setup            -> twofaHandler.VerifySetup       [settings:write]
POST /2fa/enable                  -> twofaHandler.Enable2FA         [settings:write]
POST /2fa/disable                 -> twofaHandler.Disable2FA        [settings:write]
POST /2fa/recovery-codes          -> twofaHandler.GenerateRecoveryCodes [settings:write]
POST /2fa/email/enable            -> twofaHandler.EnableEmail2FA    [settings:write]
POST /2fa/sms/enable              -> twofaHandler.EnableSMS2FA      [settings:write]
POST /2fa/backup-email            -> twofaHandler.AddBackupEmail    [settings:write]
DELETE /2fa/backup-email          -> twofaHandler.RemoveBackupEmail [settings:write]
GET    /2fa/backup-email/status   -> twofaHandler.BackupEmailStatus [settings:read]
POST /2fa/backup-email/enable     -> twofaHandler.EnableBackupEmail2FA  [settings:write]
POST /2fa/backup-email/disable    -> twofaHandler.DisableBackupEmail2FA [settings:write]
GET  /2fa/trusted-devices         -> twofaHandler.ListTrustedDevices    [settings:read]
DELETE /2fa/trusted-devices/:id   -> twofaHandler.RevokeTrustedDevice   [settings:write]
DELETE /2fa/trusted-devices       -> twofaHandler.RevokeAllTrustedDevices [settings:write]

# Phone / SMS management (settings:write, settings:read)
POST   /phone                     -> twofaHandler.AddPhone          [settings:write]
POST   /phone/verify              -> twofaHandler.VerifyPhone       [settings:write]
DELETE /phone                     -> twofaHandler.RemovePhone       [settings:write]
GET    /phone/status              -> twofaHandler.PhoneStatus       [settings:read]

# Passkey management (settings:write, settings:read)
POST   /passkey/register/begin    -> webauthnHandler.BeginRegistration   [settings:write]
POST   /passkey/register/finish   -> webauthnHandler.FinishRegistration  [settings:write]
GET    /passkeys                  -> webauthnHandler.ListCredentials     [settings:read]
PUT    /passkeys/:id              -> webauthnHandler.RenameCredential    [settings:write]
DELETE /passkeys/:id              -> webauthnHandler.DeleteCredential    [settings:write]

# Activity logs (log:read)
GET /activity-logs                -> logHandler.GetUserActivityLogs      [log:read]
GET /activity-logs/event-types    -> logHandler.GetEventTypes            [log:read]
GET /activity-logs/:id            -> logHandler.GetActivityLogByID       [log:read]
GET /activity-logs/export         -> logHandler.ExportUserActivityLogs   [log:read]

# Sessions (no extra permission)
GET    /sessions                  -> sessionHandler.ListSessions
DELETE /sessions/:id              -> sessionHandler.RevokeSession
DELETE /sessions                  -> sessionHandler.RevokeAllSessions

Admin API Routes (Admin API Key auth)

All routes use AdminAuthMiddleware(adminRepo). Header: X-Admin-API-Key.

# Metrics (Admin API Key required)
GET  /metrics                     -> healthHandler.Metrics

# Activity logs
GET /admin/activity-logs          -> logHandler.GetAllActivityLogs
GET /admin/activity-logs/export   -> logHandler.ExportAllActivityLogs

# Tenants
POST /admin/tenants               -> adminHandler.CreateTenant
GET  /admin/tenants               -> adminHandler.ListTenants

# Applications
POST /admin/apps                  -> adminHandler.CreateApp
GET  /admin/apps/:id              -> adminHandler.GetAppDetails
POST /admin/apps/:id/oauth-config -> adminHandler.UpsertOAuthConfig

# IP Rules (per-app)
GET    /admin/apps/:id/ip-rules           -> adminHandler.ListIPRules
POST   /admin/apps/:id/ip-rules           -> adminHandler.CreateIPRule
GET    /admin/apps/:id/ip-rules/:rule_id  -> adminHandler.GetIPRule
PUT    /admin/apps/:id/ip-rules/:rule_id  -> adminHandler.UpdateIPRule
DELETE /admin/apps/:id/ip-rules/:rule_id  -> adminHandler.DeleteIPRule
POST   /admin/apps/:id/ip-rules/check     -> adminHandler.CheckIPAccess

# User import/export
GET  /admin/users/export          -> adminHandler.ExportUsers
POST /admin/users/import          -> adminHandler.ImportUsers

# Trusted devices (admin)
GET    /admin/users/:id/trusted-devices -> adminHandler.ListUserTrustedDevices
DELETE /admin/users/:id/trusted-devices -> adminHandler.RevokeAllUserTrustedDevices

# Webhooks
GET    /admin/webhooks                         -> webhookHandler.AdminListEndpoints
GET    /admin/webhooks/apps/:app_id            -> webhookHandler.AdminListEndpointsByApp
POST   /admin/webhooks/apps/:app_id            -> webhookHandler.AdminCreateEndpoint
PUT    /admin/webhooks/:id/toggle              -> webhookHandler.AdminToggleEndpoint
DELETE /admin/webhooks/:id                     -> webhookHandler.AdminDeleteEndpoint
GET    /admin/webhooks/:id/deliveries          -> webhookHandler.AdminListDeliveriesByEndpoint
GET    /admin/webhooks/apps/:app_id/deliveries -> webhookHandler.AdminListDeliveriesByApp

# OIDC client management
POST   /admin/oidc/apps/:id/clients           -> oidcHandler.AdminCreateClient
GET    /admin/oidc/apps/:id/clients           -> oidcHandler.AdminListClients
GET    /admin/oidc/apps/:id/clients/:cid      -> oidcHandler.AdminGetClient
PUT    /admin/oidc/apps/:id/clients/:cid      -> oidcHandler.AdminUpdateClient
DELETE /admin/oidc/apps/:id/clients/:cid      -> oidcHandler.AdminDeleteClient
POST   /admin/oidc/apps/:id/clients/:cid/rotate-secret -> oidcHandler.AdminRotateClientSecret

# Email types
GET    /admin/email-types         -> adminHandler.ListEmailTypes
GET    /admin/email-types/:code   -> adminHandler.GetEmailType
POST   /admin/email-types         -> adminHandler.CreateEmailType
PUT    /admin/email-types/:id     -> adminHandler.UpdateEmailType
DELETE /admin/email-types/:id     -> adminHandler.DeleteEmailType

# Email templates
GET    /admin/email-templates     -> adminHandler.ListEmailTemplates
GET    /admin/email-templates/:id -> adminHandler.GetEmailTemplate
POST   /admin/email-templates     -> adminHandler.SaveEmailTemplate
DELETE /admin/email-templates/:id -> adminHandler.DeleteEmailTemplate
POST   /admin/email-templates/preview -> adminHandler.PreviewEmailTemplate

# Email variables
GET /admin/email-variables        -> adminHandler.ListWellKnownVariables

# Email server configs (per-app)
GET    /admin/apps/:id/email-config    -> adminHandler.GetEmailServerConfig
PUT    /admin/apps/:id/email-config    -> adminHandler.SaveEmailServerConfig
DELETE /admin/apps/:id/email-config    -> adminHandler.DeleteEmailServerConfig
POST   /admin/apps/:id/email-test      -> adminHandler.SendTestEmail
GET    /admin/apps/:id/email-servers   -> adminHandler.ListEmailServerConfigsByApp

# Email server configs (global CRUD)
GET    /admin/email-servers            -> adminHandler.ListAllEmailServerConfigs
GET    /admin/email-servers/:id        -> adminHandler.GetEmailServerConfigByID
POST   /admin/email-servers            -> adminHandler.CreateEmailServerConfig
PUT    /admin/email-servers/:id        -> adminHandler.UpdateEmailServerConfigByID
DELETE /admin/email-servers/:id        -> adminHandler.DeleteEmailServerConfigByID
POST   /admin/email-servers/:id/test   -> adminHandler.SendTestEmailByConfigID

# Send email
POST /admin/apps/:id/send-email  -> adminHandler.SendCustomEmail

# RBAC
GET    /admin/rbac/roles          -> rbacHandler.ListRoles
GET    /admin/rbac/roles/:id      -> rbacHandler.GetRole
POST   /admin/rbac/roles          -> rbacHandler.CreateRole
PUT    /admin/rbac/roles/:id      -> rbacHandler.UpdateRole
DELETE /admin/rbac/roles/:id      -> rbacHandler.DeleteRole
PUT    /admin/rbac/roles/:id/permissions -> rbacHandler.SetRolePermissions
GET    /admin/rbac/permissions    -> rbacHandler.ListPermissions
POST   /admin/rbac/permissions    -> rbacHandler.CreatePermission
GET    /admin/rbac/user-roles     -> rbacHandler.ListUserRoles
POST   /admin/rbac/user-roles     -> rbacHandler.AssignRole
DELETE /admin/rbac/user-roles     -> rbacHandler.RevokeRole
GET    /admin/rbac/user-roles/user -> rbacHandler.GetUserRoles

App API Routes (Per-App API Key auth)

Middleware chain: AppApiKeyMiddleware(adminRepo) + AppRouteGuardMiddleware(). Headers: X-App-API-Key + X-App-ID (must match :id in URL).

GET  /app/:id/email-config        -> adminHandler.GetEmailServerConfig
GET  /app/:id/email-servers       -> adminHandler.ListEmailServerConfigsByApp
POST /app/:id/email-test          -> adminHandler.SendTestEmail
POST /app/:id/send-email          -> adminHandler.SendCustomEmail

# Webhooks (App API Key)
GET    /app/:id/webhooks                  -> webhookHandler.AppListEndpoints
POST   /app/:id/webhooks                  -> webhookHandler.AppCreateEndpoint
PUT    /app/:id/webhooks/:wid/toggle      -> webhookHandler.AppToggleEndpoint
DELETE /app/:id/webhooks/:wid             -> webhookHandler.AppDeleteEndpoint
GET    /app/:id/webhooks/:wid/deliveries  -> webhookHandler.AppListDeliveries

OIDC Provider Routes (opt-in, requires OIDC_ENABLED on application)

GET  /.well-known/openid-configuration    -> redirect to /oidc/:app_id/.well-known/openid-configuration

GET  /oidc/:app_id/.well-known/openid-configuration -> oidcHandler.WellKnownConfiguration
GET  /oidc/:app_id/.well-known/jwks.json             -> oidcHandler.JWKS
GET  /oidc/:app_id/authorize             -> oidcHandler.Authorize              [OIDCAuthorizeRateLimit]
POST /oidc/:app_id/authorize             -> oidcHandler.AuthorizeSubmit        [OIDCAuthorizeRateLimit]
POST /oidc/:app_id/token                 -> oidcHandler.Token                  [OIDCTokenRateLimit]
GET  /oidc/:app_id/userinfo              -> oidcHandler.UserInfo               [OIDCUserInfoRateLimit]
POST /oidc/:app_id/userinfo              -> oidcHandler.UserInfo               [OIDCUserInfoRateLimit]
POST /oidc/:app_id/introspect            -> oidcHandler.Introspect             [OIDCIntrospectRateLimit]
POST /oidc/:app_id/revoke                -> oidcHandler.Revoke                 [OIDCRevokeRateLimit]
GET  /oidc/:app_id/end_session           -> oidcHandler.EndSession
POST /oidc/:app_id/end_session           -> oidcHandler.EndSession

GUI Routes (Admin Web Interface)

Static assets and login pages are public. Authenticated routes use GUIAuthMiddleware + CSRFMiddleware.

Public GUI routes

GET  /gui/static/*                -> static.HTTPFileSystem()
GET  /gui/login                   -> guiHandler.LoginPage
POST /gui/login                   -> guiHandler.LoginSubmit        [LoginRateLimit: 5/min]
POST /gui/passkey-login/begin     -> guiHandler.PasskeyLoginBegin  [GUIPasskeyLoginRateLimit: 10/min]
POST /gui/passkey-login/finish    -> guiHandler.PasskeyLoginFinish [GUIPasskeyLoginRateLimit]
POST /gui/magic-link-login        -> guiHandler.MagicLinkLoginRequest [GUIMagicLinkRateLimit: 3/15min]
GET  /gui/magic-link-login/verify -> guiHandler.MagicLinkLoginVerify
GET  /gui/2fa-verify              -> guiHandler.TwoFAVerifyPage
POST /gui/2fa-verify              -> guiHandler.TwoFAVerifySubmit
POST /gui/2fa-resend-email        -> guiHandler.TwoFAResendEmail

Authenticated GUI routes (cookie session + CSRF)

Covers: Dashboard, Tenants, Applications, OAuth, Users (with export/import, trusted device management), Logs (with CSV export), API Keys (with scope config and usage stats), Settings, Email Servers, Email Templates, Email Types, Roles, Permissions, User Roles, Sessions, Webhooks, OIDC Clients, IP Rules, Monitoring, My Account (email, password, 2FA, passkeys, magic link, backup email, trusted devices), Social Account/Passkey management for users.

Each entity follows the HTMX CRUD pattern:

GET  /gui/<entity>                -> Page (full page)
GET  /gui/<entity>/list           -> List (HTMX partial, paginated)
GET  /gui/<entity>/new            -> CreateForm (HTMX partial)
POST /gui/<entity>                -> Create
GET  /gui/<entity>/form-cancel    -> FormCancel (HTMX partial)
GET  /gui/<entity>/:id/edit       -> EditForm (HTMX partial)
PUT  /gui/<entity>/:id            -> Update
GET  /gui/<entity>/:id/delete     -> DeleteConfirm (HTMX partial)
DELETE /gui/<entity>/:id          -> Delete

Rate Limiting Summary

Endpoint Group	Prefix	Limit	Window	Lockout
GUI Login	gui:login	5/min	60s	10 attempts -> 15min lockout
API Login	api:login	5/min	60s	10 -> 15min
API Register	api:register	3/min	60s	none
API Forgot Password	api:forgot-password	3/min	60s	none
API Resend Verification	api:resend-verification	3/min	60s	none
API Refresh Token	api:refresh-token	10/min	60s	none
API Reset Password	api:reset-password	5/min	60s	none
API 2FA Verify	api:2fa-verify	5/min	60s	10 -> 15min
API Passkey Login	api:passkey-login	10/min	60s	20 -> 15min
API Passkey 2FA	api:passkey-2fa	10/min	60s	20 -> 15min
API Magic Link	api:magic-link	5/15min	15min	none
GUI Magic Link	gui:magic-link	3/15min	15min	none
GUI Passkey Login	gui:passkey-login	10/min	60s	20 -> 15min
OIDC Authorize	oidc:authorize	20/min	60s	none
OIDC Token	oidc:token	30/min	60s	none
OIDC UserInfo	oidc:userinfo	60/min	60s	none
OIDC Introspect	oidc:introspect	30/min	60s	none
OIDC Revoke	oidc:revoke	30/min	60s	none

When To Use This Skill

Load this skill when working on API endpoints, adding new routes, modifying middleware chains, changing rate limits, or debugging request flows.