Authentication & Authorization

What is Authentication?

Security in web applications comes down to two fundamental questions: Who are you? and What are you allowed to do? These are handled by two separate systems that work together.

Grit handles both: JWT tokens for authentication and roles for authorization. Every API request goes through this two-step check: first, is the token valid? Second, does this user's role allow this action?

How JWT Authentication Works

Grit uses JSON Web Tokens (JWTs) for authentication. Here is the complete flow, step by step:

1. 1. User sends email + password to POST /api/auth/register or POST /api/auth/login
2. 2. Server verifies credentials against the database (password hashed with bcrypt)
3. 3. Server creates two tokens: an access token (short-lived, 15 minutes) and a refresh token (long-lived, 7 days)
4. 4. Frontend stores both tokens
5. 5. Every API request includes the access token in the Authorization header
6. 6. When the access token expires, the frontend uses the refresh token to get a new one
7. 7. When the refresh token expires, the user must log in again

Here is what happens when you register a new user:

// Request
{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "securePassword123"
}

// Response
{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "role": "USER"
    }
  }
}

Notice the response includes both tokens and the user object. The password is never returned. Logging in works the same way:

{
  "email": "john@example.com",
  "password": "securePassword123"
}

Once you have the access token, every subsequent API request must include it in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Where Auth Lives in the Code

Grit's auth system is spread across four key files. Understanding where each piece lives helps you customize the auth behavior:

• • apps/api/internal/handlers/auth.go — Register, Login, RefreshToken, and GetMe handlers
• • apps/api/internal/services/auth_service.go — Password hashing, token generation, user lookup
• • apps/api/internal/middleware/auth.go — JWT verification middleware
• • apps/api/internal/routes/routes.go — Public vs protected route groups

The most important concept is the split between public and protected routes:

// Public routes — no authentication required
public := r.Group("/api/auth")
public.POST("/register", authHandler.Register)
public.POST("/login", authHandler.Login)
public.POST("/refresh", authHandler.RefreshToken)

// Protected routes — JWT required
protected := r.Group("/api")
protected.Use(middleware.Auth(cfg.JWTSecret))
protected.GET("/users", userHandler.List)
protected.GET("/me", authHandler.GetMe)

Routes inside the "protected" group require a valid JWT. The Auth middleware runs before the handler and checks the token. If the token is missing, expired, or tampered with, the middleware returns 401 Unauthorized immediately and the handler never executes.

Roles and Role-Based Access Control

Authentication tells you who the user is. But that is only half the story. You also need to control what each user can do. Grit solves this with three built-in roles:

• ADMIN — Full access to everything: manage users, system settings, all resources
• EDITOR — Can create, edit, and publish content, but cannot manage users or system settings
• USER — Basic access: their own profile and public content

Here is how role-restricted routes look in Grit:

// Only ADMIN can access these
admin := protected.Group("/admin")
admin.Use(middleware.RequireRole("ADMIN"))
admin.DELETE("/users/:id", userHandler.Delete)
admin.PUT("/users/:id/role", userHandler.UpdateRole)

The RequireRole middleware checks the user's role (which was set by the Auth middleware earlier). If the role does not match, the request is rejected with 403 Forbidden.

Here is the User model with the role field:

type User struct {
    gorm.Model
    Name     string `gorm:"not null" json:"name"`
    Email    string `gorm:"uniqueIndex;not null" json:"email"`
    Password string `gorm:"not null" json:"-"`
    Role     string `gorm:"default:USER" json:"role"`
}

Two important details: json:"-" means the Password field is never included in API responses — it is invisible to the frontend. The Role field defaults to USER for all new registrations, so no one can register themselves as an ADMIN.

Adding Custom Roles

Three roles might not be enough for your app. A forum might need a MODERATOR. A marketplace might need a VENDOR. Grit makes adding custom roles easy:

grit add role MODERATOR

This single command updates four places across your stack:

1. 1. Go models — adds MODERATOR to the role constants
2. 2. TypeScript types — adds "MODERATOR" to the role union type
3. 3. Zod schemas — adds "MODERATOR" to the role validation
4. 4. Admin UI — adds MODERATOR as an option in role dropdowns

You can also restrict generated resources to specific roles:

grit generate resource Report --fields "title:string,content:text" --roles "ADMIN,MODERATOR"

This generates routes that only ADMIN and MODERATOR can access. A regular USER trying to reach /api/reports will get 403 Forbidden.

Two-Factor Authentication (TOTP)

Passwords alone are not enough. They can be guessed, phished, or leaked in data breaches. TOTP adds a second layer of security: even if someone steals your password, they cannot log in without the code from your authenticator app.

Here is how Grit's TOTP system works:

1. 1. User calls POST /api/totp/setup — server generates a secret key and returns a QR code URL
2. 2. User scans the QR code with their authenticator app (Google Authenticator, Authy, etc.)
3. 3. User enters the 6-digit code to verify: POST /api/totp/verify
4. 4. Server stores that 2FA is enabled for this user
5. 5. On next login, after the password check, the server asks for the TOTP code
6. 6. User enters the code from their app — if it matches, login succeeds

Here is the setup flow:

// Request (requires Authorization header)
POST /api/totp/setup
Authorization: Bearer <token>

// Response
{
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qr_url": "otpauth://totp/myapp:john@example.com?secret=JBSWY3DPEHPK3PXP&issuer=myapp",
    "backup_codes": [
      "a1b2c3d4",
      "e5f6g7h8",
      "i9j0k1l2",
      "m3n4o5p6",
      "q7r8s9t0",
      "u1v2w3x4",
      "y5z6a7b8",
      "c9d0e1f2",
      "g3h4i5j6",
      "k7l8m9n0"
    ]
  }
}

The qr_url follows the otpauth:// URI format that all authenticator apps understand. The secret is the raw key — you can enter it manually if you cannot scan the QR code.

Backup Codes

What if you lose your phone? Or your authenticator app gets deleted? You would be locked out of your account forever. That is where backup codes come in.

Grit generates 10 backup codes during TOTP setup. Each code is a one-time-use alternative to the TOTP code. They are hashed with bcrypt before being stored in the database — just like passwords, even if someone steals the database, they cannot read the backup codes.

To use a backup code, send it to the verify endpoint instead of a TOTP code:

{
  "code": "a1b2c3d4"
}

The server checks: is this a valid TOTP code? If not, is it a valid backup code? If it matches a backup code, the code is marked as used and can never be used again.

Trusted Devices

Entering a TOTP code every single time you log in from your own computer gets annoying fast. Grit solves this with trusted devices.

When you verify a TOTP code, you can set a "trust this device" flag. The server creates a secure cookie that lasts 30 days. During those 30 days, that browser skips the TOTP step entirely — password only. After 30 days, or if you clear your cookies, you will need to enter a TOTP code again.

OAuth2 Social Login

Not everyone wants to create yet another password. OAuth2 lets users sign in with their existing Google or GitHub account instead.

Grit uses the goth library for OAuth2. You configure it by adding client credentials to your .env file:

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Here is the complete OAuth2 flow:

1. 1. User clicks "Sign in with Google" on your login page
2. 2. Browser redirects to Google's login page
3. 3. User logs in with their Google account
4. 4. Google redirects back to your app with a temporary code
5. 5. Your API exchanges the code for the user's email and name
6. 6. If the email already exists in your database, the accounts are linked
7. 7. If it is a new email, a new account is created automatically

The JWT_SECRET

The JWT_SECRET is arguably the most important configuration value in your app. It is the key used to sign and verify every JWT token. Anyone who has this secret can create valid tokens for any user — including admin tokens.

This is why:

• • It must be long and random (at least 32 characters)
• • It must never be committed to Git (it is in .env, which is in .gitignore)
• • It must be different in development and production

Here is how to generate a cryptographically strong secret:

openssl rand -hex 32
# Output: a3f8b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1

Auth in the Frontend

The backend handles token creation and verification, but the frontend is responsible for storing tokens, attaching them to requests, and managing auth state. Here is how Grit's web app handles it:

• • On login: stores the access_token and refresh_token
• • On every API call: attaches the Authorization: Bearer <token> header automatically
• • When access token expires: automatically calls /api/auth/refresh to get a new one
• • On logout: clears both tokens and redirects to the login page
• • Auth context: a React context that provides user data and auth state to all components

Protected pages use the auth hook to redirect unauthenticated users:

// If not logged in, redirect to /login
const { user, isLoading } = useAuth()
if (!isLoading && !user) redirect("/login")

This pattern runs on every protected page. While isLoading is true (the auth state is being checked), the page shows a loading spinner. Once loading completes, if there is no user, the visitor is immediately redirected to the login page. They never see the protected content.

Summary

You now understand Grit's complete auth system, from password hashing to social login. Here is everything you learned:

• Authentication vs authorization — who you are vs what you can do
• JWT flow — register, login, access token (15 min), refresh token (7 days)
• bcrypt password hashing — one-way hashing, never store plain text
• Middleware-based route protection — Auth middleware checks tokens, RequireRole checks permissions
• 3 built-in roles — ADMIN, EDITOR, USER — plus custom roles with grit add role
• TOTP two-factor authentication — 6-digit codes from authenticator apps, QR code setup
• Backup codes — 10 one-time-use recovery codes, bcrypt-hashed in the database
• Trusted devices — 30-day secure cookies to skip TOTP on known browsers
• OAuth2 social login — Google and GitHub sign-in via the goth library
• JWT_SECRET security — random, never committed, change to invalidate all sessions
• Frontend auth flow — token storage, auto-refresh, protected routes, auth context