Authentication is one of the most important parts of modern backend development.
If you are building a REST API, mobile app backend, SaaS platform, admin panel, marketplace, or microservice in Go, you usually need a secure way to identify users and protect private routes.
JWT, or JSON Web Token, is a common approach for token-based authentication.
In this guide, you will learn how JWT authentication works in Go, how to register and log in users, hash passwords, generate access tokens, validate JWTs, protect routes with middleware, handle token expiry, use refresh tokens, store secrets safely, and avoid common security mistakes.
What Is JWT Authentication?
JWT stands for:
JSON Web Token
A JWT is a signed token that can carry information about a user.
A basic authentication flow looks like this:
User
|
| Email + Password
v
Go Backend
|
| Verify credentials
v
Generate JWT
|
v
Client stores token
|
| Authorization header
v
Protected API
The client usually sends the token like this:
Authorization: Bearer YOUR_TOKEN
The server verifies the token before allowing access to protected endpoints.
What Does a JWT Look Like?
A JWT contains three parts:
Header.Payload.Signature
For example:
xxxxx.yyyyy.zzzzz
The three parts are:
Header
Payload
Signature
JWT Header
The header describes the token type and signing algorithm.
Conceptually:
{
"alg": "HS256",
"typ": "JWT"
}
JWT Payload
The payload contains claims.
For example:
{
"user_id": 12,
"email": "john@example.com",
"exp": 1790000000
}
Claims can include:
User ID
Email
Role
Issuer
Expiration time
Issued-at time
Important: JWT payload data is encoded, not encrypted.
Do not put passwords or sensitive secrets inside JWT claims.
JWT Signature
The signature allows the server to verify that the token has not been modified.
For HMAC-based JWTs, the server signs the token using a secret key.
Conceptually:
Header + Payload + Secret
↓
Signature
If someone changes the token payload without the correct signing secret, verification fails.
JWT Authentication Flow
A common flow is:
1. User registers
2. Password is hashed
3. User logs in
4. Server verifies password
5. Server creates JWT
6. Client stores JWT
7. Client sends JWT with requests
8. Server validates JWT
9. Protected endpoint executes
Step 1: Create a Go Project
Create a project:
mkdir go-jwt-auth
Enter it:
cd go-jwt-auth
Initialize:
go mod init go-jwt-auth
Create:
main.go
Step 2: Install a JWT Library
A commonly used JWT library for Go is:
github.com/golang-jwt/jwt/v5
Install:
go get github.com/golang-jwt/jwt/v5
Step 3: Install bcrypt
Passwords should never be stored as plain text.
Install:
go get golang.org/x/crypto/bcrypt
bcrypt allows you to hash passwords securely.
Basic Project Structure
A simple project may look like:
go-jwt-auth/
│
├── main.go
├── go.mod
└── go.sum
A larger project can later use:
cmd/
internal/
handlers/
services/
repositories/
middleware/
models/
auth/
Create a User Model
Example:
type User struct {
ID int
Email string
Password string
}
In a real application, the Password field should store a password hash, not the original password.
A clearer model could be:
type User struct {
ID int
Email string
PasswordHash string
}
Never Store Plain-Text Passwords
Do not store:
mypassword123
directly in your database.
Instead:
Password
|
v
bcrypt
|
v
Password Hash
The stored result might look similar to:
$2a$12$...
Hash a Password with bcrypt
Create:
func hashPassword(
password string,
) (string, error) {
hashedPassword, err :=
bcrypt.GenerateFromPassword(
[]byte(password),
bcrypt.DefaultCost,
)
if err != nil {
return "", err
}
return string(
hashedPassword,
), nil
}
Use:
hashedPassword, err :=
hashPassword(
"myPassword123",
)
Store hashedPassword in your database.
Verify a Password
When the user logs in, compare the provided password with the stored hash.
func checkPassword(
password string,
passwordHash string,
) bool {
err :=
bcrypt.CompareHashAndPassword(
[]byte(passwordHash),
[]byte(password),
)
return err == nil
}
Example:
if !checkPassword(
request.Password,
user.PasswordHash,
) {
// Invalid password
}
Step 4: Create a JWT Secret
You need a signing secret.
Do not write production secrets directly in code like:
var jwtSecret =
[]byte("my-secret")
Instead, store the secret in an environment variable.
Example:
JWT_SECRET=very-long-random-secret
Read it:
jwtSecret :=
os.Getenv(
"JWT_SECRET",
)
Check:
if jwtSecret == "" {
log.Fatal(
"JWT_SECRET is required",
)
}
JWT Claims
You can create custom claims.
Example:
type Claims struct {
UserID int `json:"user_id"`
Email string `json:"email"`
jwt.RegisteredClaims
}
RegisteredClaims supports standard claims such as:
exp
iat
nbf
iss
sub
aud
Generate a JWT Token
Example:
func generateToken(
user User,
secret string,
) (string, error) {
claims :=
Claims{
UserID:
user.ID,
Email:
user.Email,
RegisteredClaims:
jwt.RegisteredClaims{
ExpiresAt:
jwt.NewNumericDate(
time.Now().
Add(
15 *
time.Minute,
),
),
IssuedAt:
jwt.NewNumericDate(
time.Now(),
),
},
}
token :=
jwt.NewWithClaims(
jwt.SigningMethodHS256,
claims,
)
return token.SignedString(
[]byte(secret),
)
}
This token expires after:
15 minutes
Why Should JWTs Expire?
Tokens should not normally remain valid forever.
If a token is stolen and never expires, an attacker could keep using it.
Short-lived access tokens reduce the impact.
For example:
Access Token
Expires in 15 minutes
You can then use a refresh token to obtain a new access token.
Register User Flow
A typical registration flow is:
POST /register
|
v
Validate input
|
v
Check existing email
|
v
Hash password
|
v
Insert user
|
v
Return success
Registration Request Model
type RegisterRequest struct {
Email string `json:"email"`
Password string `json:"password"`
}
Registration Handler Example
For simplicity, assume database insertion is handled by another function.
func registerHandler(
w http.ResponseWriter,
r *http.Request,
) {
if r.Method !=
http.MethodPost {
http.Error(
w,
"Method not allowed",
http.StatusMethodNotAllowed,
)
return
}
var request RegisterRequest
err :=
json.NewDecoder(
r.Body,
).Decode(
&request,
)
if err != nil {
http.Error(
w,
"Invalid request",
http.StatusBadRequest,
)
return
}
if request.Email == "" ||
request.Password == "" {
http.Error(
w,
"Email and password are required",
http.StatusBadRequest,
)
return
}
hashedPassword, err :=
hashPassword(
request.Password,
)
if err != nil {
http.Error(
w,
"Unable to register",
http.StatusInternalServerError,
)
return
}
_ = hashedPassword
w.WriteHeader(
http.StatusCreated,
)
w.Write(
[]byte(
"User registered successfully",
),
)
}
In a real application, save the hashed password to PostgreSQL or MySQL.
Login Flow
A common login process looks like:
POST /login
|
v
Find user by email
|
v
Compare password
|
v
Generate JWT
|
v
Return token
Login Request
type LoginRequest struct {
Email string `json:"email"`
Password string `json:"password"`
}
Login Response
type LoginResponse struct {
AccessToken string `json:"access_token"`
}
Login Handler Example
For learning, assume a user has already been retrieved from the database.
func loginHandler(
secret string,
) http.HandlerFunc {
return func(
w http.ResponseWriter,
r *http.Request,
) {
if r.Method !=
http.MethodPost {
http.Error(
w,
"Method not allowed",
http.StatusMethodNotAllowed,
)
return
}
var request LoginRequest
err :=
json.NewDecoder(
r.Body,
).Decode(
&request,
)
if err != nil {
http.Error(
w,
"Invalid request",
http.StatusBadRequest,
)
return
}
user :=
User{
ID: 1,
Email:
"john@example.com",
PasswordHash:
"$2a$...",
}
if !checkPassword(
request.Password,
user.PasswordHash,
) {
http.Error(
w,
"Invalid email or password",
http.StatusUnauthorized,
)
return
}
token, err :=
generateToken(
user,
secret,
)
if err != nil {
http.Error(
w,
"Unable to generate token",
http.StatusInternalServerError,
)
return
}
response :=
LoginResponse{
AccessToken:
token,
}
w.Header().Set(
"Content-Type",
"application/json",
)
json.NewEncoder(
w,
).Encode(
response,
)
}
}
In production, fetch the user from your database instead of hardcoding it.
JWT Login Response Example
A successful login might return:
{
"access_token": "eyJhbGciOiJIUzI1NiIs..."
}
The client then sends this token on protected requests.
Authorization Header
A protected request normally includes:
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
The format is:
Bearer TOKEN
Step 5: Extract the Bearer Token
Create a helper:
func extractBearerToken(
r *http.Request,
) (string, error) {
authHeader :=
r.Header.Get(
"Authorization",
)
if authHeader == "" {
return "",
errors.New(
"authorization header missing",
)
}
parts :=
strings.SplitN(
authHeader,
" ",
2,
)
if len(parts) != 2 ||
!strings.EqualFold(
parts[0],
"Bearer",
) {
return "",
errors.New(
"invalid authorization header",
)
}
return parts[1], nil
}
Step 6: Validate a JWT
Create:
func validateToken(
tokenString string,
secret string,
) (*Claims, error) {
token, err :=
jwt.ParseWithClaims(
tokenString,
&Claims{},
func(
token *jwt.Token,
) (interface{}, error) {
if token.Method !=
jwt.SigningMethodHS256 {
return nil,
errors.New(
"unexpected signing method",
)
}
return []byte(secret),
nil
},
)
if err != nil {
return nil, err
}
claims, ok :=
token.Claims.(*Claims)
if !ok ||
!token.Valid {
return nil,
errors.New(
"invalid token",
)
}
return claims, nil
}
Why Verify the Signing Algorithm?
Do not blindly accept whatever signing algorithm appears in the incoming token.
Your application should know which algorithm it expects.
In this example:
jwt.SigningMethodHS256
is required.
This reduces the risk of accepting improperly signed tokens.
Step 7: Create JWT Middleware
Middleware can protect private routes.
Example:
func authMiddleware(
secret string,
next http.Handler,
) http.Handler {
return http.HandlerFunc(
func(
w http.ResponseWriter,
r *http.Request,
) {
tokenString, err :=
extractBearerToken(r)
if err != nil {
http.Error(
w,
"Unauthorized",
http.StatusUnauthorized,
)
return
}
claims, err :=
validateToken(
tokenString,
secret,
)
if err != nil {
http.Error(
w,
"Unauthorized",
http.StatusUnauthorized,
)
return
}
ctx :=
context.WithValue(
r.Context(),
userClaimsKey,
claims,
)
next.ServeHTTP(
w,
r.WithContext(ctx),
)
},
)
}
Avoid Plain String Context Keys
Instead of:
context.WithValue(
ctx,
"user",
claims,
)
create a private custom type:
type contextKey string
Then:
const userClaimsKey contextKey =
"userClaims"
This reduces accidental context-key collisions.
Read JWT Claims from Context
A protected handler can retrieve claims:
func profileHandler(
w http.ResponseWriter,
r *http.Request,
) {
claims, ok :=
r.Context().
Value(
userClaimsKey,
).
(*Claims)
if !ok {
http.Error(
w,
"Unauthorized",
http.StatusUnauthorized,
)
return
}
fmt.Fprintf(
w,
"User ID: %d",
claims.UserID,
)
}
Protect a Route
Create:
mux :=
http.NewServeMux()
Public route:
mux.HandleFunc(
"/login",
loginHandler(secret),
)
Protected route:
profile :=
http.HandlerFunc(
profileHandler,
)
mux.Handle(
"/profile",
authMiddleware(
secret,
profile,
),
)
Now /profile requires a valid JWT.
Public vs Protected Routes
Your application may look like:
Public Routes
-------------
POST /register
POST /login
Protected Routes
----------------
GET /profile
GET /orders
POST /posts
PUT /account
DELETE /account
JWT middleware runs only on protected routes.
Role-Based Authorization
Authentication answers:
Who is the user?
Authorization answers:
What is this user allowed to do?
You can add a role claim.
Example:
type Claims struct {
UserID int `json:"user_id"`
Email string `json:"email"`
Role string `json:"role"`
jwt.RegisteredClaims
}
Possible roles:
user
admin
moderator
seller
Admin Authorization Example
func adminHandler(
w http.ResponseWriter,
r *http.Request,
) {
claims, ok :=
r.Context().
Value(
userClaimsKey,
).
(*Claims)
if !ok ||
claims.Role != "admin" {
http.Error(
w,
"Forbidden",
http.StatusForbidden,
)
return
}
fmt.Fprintln(
w,
"Welcome admin",
)
}
401 vs 403
These are easy to confuse.
Use:
401 Unauthorized
when authentication is missing or invalid.
For example:
No JWT
Expired JWT
Invalid JWT
Use:
403 Forbidden
when the user is authenticated but lacks permission.
Example:
Normal user trying to access admin route
Access Tokens
An access token is typically short-lived.
Example:
15 minutes
It is sent with API requests:
Authorization: Bearer ACCESS_TOKEN
Refresh Tokens
A refresh token allows a user to obtain a new access token without entering credentials again.
Conceptually:
Login
|
+---- Access Token
|
+---- Refresh Token
Later:
Access token expires
|
v
Send refresh token
|
v
Verify refresh token
|
v
Issue new access token
Why Use Refresh Tokens?
If you make an access token valid for:
30 days
a stolen token can remain useful for a long time.
Instead:
Access Token
15 minutes
Refresh Token
Longer lifetime
This allows short-lived API access while maintaining a convenient user session.
Access Token Claims
A good access token may contain:
User ID
Role
Issued at
Expiration
Issuer
Subject
Avoid adding unnecessary personal data.
Refresh Token Storage
Refresh tokens often require stricter handling than access tokens.
Depending on your application architecture, refresh tokens may be:
Stored server-side in a database
Stored as a hash
Rotated after use
Revoked on logout
Placed in secure HTTP-only cookies
Mobile applications may store tokens using platform secure storage.
The exact approach depends on the client and threat model.
Refresh Token Rotation
A stronger refresh-token strategy is rotation.
Flow:
Refresh Token A
|
v
Used once
|
v
Token A invalidated
|
v
Refresh Token B created
If an old refresh token is reused unexpectedly, the server may detect suspicious activity.
JWT Logout
A JWT is stateless by nature.
That means simply deleting the token from the client logs the user out locally, but the token itself may technically remain valid until expiry.
For stronger logout control, you can use strategies such as:
Short access-token expiry
Refresh-token revocation
Session table
Token version
Denylist for selected tokens
Token Version Strategy
A user record might include:
token_version
The JWT includes:
{
"user_id": 10,
"token_version": 3
}
If you increase the database value to:
4
old tokens with version 3 can be rejected.
This can help support:
Logout from all devices
Password reset
Account compromise response
JWT with PostgreSQL or MySQL
JWT authentication usually works together with a database.
For example:
POST /login
|
v
SELECT user by email
|
v
Compare bcrypt hash
|
v
Generate JWT
Database table:
CREATE TABLE users (
id BIGSERIAL PRIMARY KEY,
email VARCHAR(255) UNIQUE NOT NULL,
password_hash TEXT NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
For MySQL, you might use an AUTO_INCREMENT primary key instead.
User Repository Example
Conceptually:
type UserRepository struct {
db *sql.DB
}
Then:
func (
r *UserRepository,
) GetByEmail(
ctx context.Context,
email string,
) (*User, error) {
var user User
err :=
r.db.QueryRowContext(
ctx,
`
SELECT
id,
email,
password_hash
FROM users
WHERE email = $1
`,
email,
).Scan(
&user.ID,
&user.Email,
&user.PasswordHash,
)
if err != nil {
return nil, err
}
return &user, nil
}
The placeholder above is PostgreSQL-style.
For MySQL, use:
?
instead.
Secure Login Error Messages
Avoid revealing whether a specific email exists.
Instead of:
Email exists but password is wrong
return:
Invalid email or password
This makes account enumeration harder.
Validate Login Input
Check:
Email present
Password present
Valid email format
Reasonable password length
Request body size
Do not allow arbitrary huge request bodies.
Example:
r.Body =
http.MaxBytesReader(
w,
r.Body,
1<<20,
)
This limits the body to around 1 MB.
For login requests, you can choose a much smaller limit.
Password Rules
Passwords should not be stored or logged in plain text.
At a minimum, consider enforcing reasonable password requirements.
Avoid weak rules based only on things like:
Must contain exactly one symbol
Must contain exactly one uppercase letter
Length is one of the most important factors.
The application should also consider rate limiting and compromised-password protections where appropriate.
Brute-Force Protection
JWT does not protect the login endpoint from password guessing.
Consider:
Rate limiting
Login attempt monitoring
Temporary delays
Account security alerts
IP/device signals
Multi-factor authentication
for higher-security systems.
Never Log Tokens
Avoid logs such as:
JWT: eyJhbGciOi...
Access and refresh tokens are credentials.
If leaked through logs, they may be abused.
Never Put Passwords in JWTs
Bad:
{
"email": "john@example.com",
"password": "password123"
}
Never do this.
A token should contain only the minimum claims required by your application.
JWT Is Signed, Not Encrypted
This is crucial.
Someone who has the JWT can usually decode its header and payload.
They should not be able to modify it successfully without the signing key, but they can often read its claims.
Therefore, avoid storing secrets in the payload.
HMAC vs RSA/ECDSA JWT Signing
JWT supports multiple signing algorithms.
HMAC algorithms such as:
HS256
use the same secret for signing and verifying.
Asymmetric algorithms such as:
RS256
ES256
use:
Private key → signing
Public key → verification
Asymmetric signing can be useful in distributed systems where multiple services need to verify tokens without receiving the private signing key.
JWT Issuer Claim
You can specify:
Issuer:
"my-api",
Then verify tokens were created by your own authentication system.
JWT Subject Claim
The standard subject claim is:
sub
It often represents the user ID.
Example:
Subject:
strconv.Itoa(
user.ID,
),
Using standard claims can make your authentication system clearer.
JWT Audience
The audience claim:
aud
can identify which application or API the token is intended for.
This becomes particularly useful when tokens are shared across several services or clients.
Clock and Expiry Handling
Authentication systems rely on time-based claims such as:
exp
iat
nbf
Make sure production servers use reliable system clocks.
Tokens should be rejected when they are expired or not yet valid.
Complete JWT Authentication Example
The following example demonstrates a small in-memory authentication flow for learning purposes.
It is intentionally simplified. A production system should use a database for users and refresh sessions.
package main
import (
"context"
"encoding/json"
"errors"
"log"
"net/http"
"os"
"strings"
"time"
"github.com/golang-jwt/jwt/v5"
"golang.org/x/crypto/bcrypt"
)
type User struct {
ID int
Email string
PasswordHash string
}
type Claims struct {
UserID int `json:"user_id"`
Email string `json:"email"`
jwt.RegisteredClaims
}
type LoginRequest struct {
Email string `json:"email"`
Password string `json:"password"`
}
type LoginResponse struct {
AccessToken string `json:"access_token"`
}
type contextKey string
const userClaimsKey contextKey =
"userClaims"
func hashPassword(
password string,
) (string, error) {
hash, err :=
bcrypt.GenerateFromPassword(
[]byte(password),
bcrypt.DefaultCost,
)
if err != nil {
return "", err
}
return string(hash), nil
}
func checkPassword(
password string,
hash string,
) bool {
return bcrypt.
CompareHashAndPassword(
[]byte(hash),
[]byte(password),
) == nil
}
func generateToken(
user User,
secret string,
) (string, error) {
now :=
time.Now()
claims :=
Claims{
UserID:
user.ID,
Email:
user.Email,
RegisteredClaims:
jwt.RegisteredClaims{
IssuedAt:
jwt.NewNumericDate(
now,
),
ExpiresAt:
jwt.NewNumericDate(
now.Add(
15 *
time.Minute,
),
),
Issuer:
"go-jwt-api",
},
}
token :=
jwt.NewWithClaims(
jwt.SigningMethodHS256,
claims,
)
return token.SignedString(
[]byte(secret),
)
}
func validateToken(
tokenString string,
secret string,
) (*Claims, error) {
token, err :=
jwt.ParseWithClaims(
tokenString,
&Claims{},
func(
token *jwt.Token,
) (interface{}, error) {
if token.Method !=
jwt.SigningMethodHS256 {
return nil,
errors.New(
"unexpected signing method",
)
}
return []byte(secret),
nil
},
)
if err != nil {
return nil, err
}
claims, ok :=
token.Claims.(*Claims)
if !ok ||
!token.Valid {
return nil,
errors.New(
"invalid token",
)
}
return claims, nil
}
func extractBearerToken(
r *http.Request,
) (string, error) {
header :=
r.Header.Get(
"Authorization",
)
parts :=
strings.SplitN(
header,
" ",
2,
)
if len(parts) != 2 ||
!strings.EqualFold(
parts[0],
"Bearer",
) {
return "",
errors.New(
"invalid authorization header",
)
}
if strings.TrimSpace(
parts[1],
) == "" {
return "",
errors.New(
"token missing",
)
}
return parts[1], nil
}
func authMiddleware(
secret string,
next http.Handler,
) http.Handler {
return http.HandlerFunc(
func(
w http.ResponseWriter,
r *http.Request,
) {
tokenString, err :=
extractBearerToken(
r,
)
if err != nil {
http.Error(
w,
"Unauthorized",
http.StatusUnauthorized,
)
return
}
claims, err :=
validateToken(
tokenString,
secret,
)
if err != nil {
http.Error(
w,
"Unauthorized",
http.StatusUnauthorized,
)
return
}
ctx :=
context.WithValue(
r.Context(),
userClaimsKey,
claims,
)
next.ServeHTTP(
w,
r.WithContext(ctx),
)
},
)
}
func loginHandler(
secret string,
user User,
) http.HandlerFunc {
return func(
w http.ResponseWriter,
r *http.Request,
) {
if r.Method !=
http.MethodPost {
http.Error(
w,
"Method not allowed",
http.StatusMethodNotAllowed,
)
return
}
var request LoginRequest
err :=
json.NewDecoder(
r.Body,
).Decode(
&request,
)
if err != nil {
http.Error(
w,
"Invalid request",
http.StatusBadRequest,
)
return
}
if request.Email !=
user.Email ||
!checkPassword(
request.Password,
user.PasswordHash,
) {
http.Error(
w,
"Invalid email or password",
http.StatusUnauthorized,
)
return
}
accessToken, err :=
generateToken(
user,
secret,
)
if err != nil {
http.Error(
w,
"Unable to login",
http.StatusInternalServerError,
)
return
}
w.Header().Set(
"Content-Type",
"application/json",
)
json.NewEncoder(
w,
).Encode(
LoginResponse{
AccessToken:
accessToken,
},
)
}
}
func profileHandler(
w http.ResponseWriter,
r *http.Request,
) {
claims, ok :=
r.Context().
Value(
userClaimsKey,
).
(*Claims)
if !ok {
http.Error(
w,
"Unauthorized",
http.StatusUnauthorized,
)
return
}
w.Header().Set(
"Content-Type",
"application/json",
)
json.NewEncoder(
w,
).Encode(
map[string]interface{}{
"user_id":
claims.UserID,
"email":
claims.Email,
},
)
}
func main() {
secret :=
os.Getenv(
"JWT_SECRET",
)
if secret == "" {
log.Fatal(
"JWT_SECRET is required",
)
}
passwordHash, err :=
hashPassword(
"password123",
)
if err != nil {
log.Fatal(err)
}
user :=
User{
ID:
1,
Email:
"john@example.com",
PasswordHash:
passwordHash,
}
mux :=
http.NewServeMux()
mux.HandleFunc(
"/login",
loginHandler(
secret,
user,
),
)
profile :=
http.HandlerFunc(
profileHandler,
)
mux.Handle(
"/profile",
authMiddleware(
secret,
profile,
),
)
server :=
&http.Server{
Addr:
":8080",
Handler:
mux,
ReadHeaderTimeout:
5 * time.Second,
}
log.Println(
"Server running on :8080",
)
log.Fatal(
server.ListenAndServe(),
)
}
Run the Example
Set your JWT secret:
export JWT_SECRET="replace-this-with-a-long-random-secret"
Run:
go run main.go
Test Login with curl
Send:
curl -X POST \
http://localhost:8080/login \
-H "Content-Type: application/json" \
-d '{
"email":"john@example.com",
"password":"password123"
}'
Successful response:
{
"access_token": "YOUR_JWT_TOKEN"
}
Test the Protected Route
Copy the token and send:
curl \
http://localhost:8080/profile \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response:
{
"user_id": 1,
"email": "john@example.com"
}
Without a valid token, the server returns:
401 Unauthorized
Recommended Authentication Architecture
For a larger Go backend:
Client
|
v
HTTP Handler
|
v
Auth Service
|
+---- Password Hashing
|
+---- JWT Service
|
v
User Repository
|
v
Database
Project structure:
go-api/
│
├── cmd/
│ └── api/
│ └── main.go
│
├── internal/
│ ├── auth/
│ │ └── jwt.go
│ │
│ ├── middleware/
│ │ └── auth.go
│ │
│ ├── handlers/
│ │ └── auth_handler.go
│ │
│ ├── services/
│ │ └── auth_service.go
│ │
│ ├── repositories/
│ │ └── user_repository.go
│ │
│ └── models/
│ └── user.go
│
├── go.mod
└── go.sum
What Goes in the JWT Package?
A dedicated JWT package may handle:
Generate access token
Validate access token
Generate refresh token
Validate refresh token
Token expiry
Claims
Signing configuration
This keeps authentication logic separate from HTTP handlers.
What Goes in Authentication Middleware?
Middleware should generally:
Read Authorization header
Extract Bearer token
Validate JWT
Read claims
Attach authenticated identity to context
Continue request
It should not contain your entire user-management system.
What Goes in Auth Service?
Your authentication service can handle:
Register
Login
Password comparison
Token generation
Refresh session
Logout
Password reset
Account security
JWT vs Session Authentication
JWT is not the only authentication method.
Traditional session authentication works like:
Login
|
v
Create server-side session
|
v
Send session cookie
JWT often works like:
Login
|
v
Create signed token
|
v
Client sends token
Neither is automatically better for every application.
Sessions can be easier to revoke centrally.
JWTs can be useful for APIs and distributed architectures when designed correctly.
JWT for Mobile Apps
For Flutter, Android, or iOS applications, a common flow is:
Mobile App
|
POST /login
|
v
Go Backend
|
v
Access + Refresh Token
|
v
Secure Storage
Then API requests include:
Authorization: Bearer ACCESS_TOKEN
Do not store important authentication tokens in plain-text storage where a secure platform storage option is available.
JWT for Web Applications
Web applications require special consideration because JavaScript-accessible storage can be exposed by XSS.
Depending on architecture, authentication tokens or refresh tokens may be placed in:
Secure cookies
HttpOnly cookies
SameSite cookies
If cookies are used, also understand CSRF protections.
The right approach depends on how your frontend and backend are deployed.
JWT Security Best Practices
For production authentication:
- use HTTPS
- hash passwords with a proper password-hashing algorithm such as bcrypt
- use strong signing secrets or keys
- store secrets outside source code
- keep access tokens short-lived
- validate token expiry
- validate the expected signing algorithm
- consider issuer and audience validation
- do not store passwords or secrets in JWT claims
- do not log tokens
- protect login endpoints from brute-force attempts
- use refresh-token rotation when appropriate
- revoke refresh sessions on logout
- securely store client-side credentials
- use database constraints for unique user identities
- provide account recovery carefully
- monitor suspicious authentication activity
Common JWT Authentication Mistakes
Common mistakes include:
Hardcoding JWT secrets
Never expiring tokens
Putting passwords in JWT payloads
Trusting decoded claims without verifying signature
Accepting unexpected algorithms
Returning detailed login errors
Using long-lived access tokens
Logging JWTs
No rate limiting on login
No refresh-token revocation
Storing passwords in plain text
Using HTTP instead of HTTPS
JWT Decoding Is Not JWT Validation
This is extremely important.
Decoding means:
Read token payload
Validation means:
Verify signature
Check expiry
Check expected algorithm
Validate relevant claims
Never authorize a user based only on decoded token data.
Should You Query the Database on Every JWT Request?
It depends on your application.
Pure stateless authentication may trust validated token claims until the token expires.
But some systems also query the database to verify:
User still exists
Account is active
Role has not changed
Token version matches
Session is not revoked
This provides more control but adds database work.
A common compromise is short-lived access tokens plus server-managed refresh sessions.
Frequently Asked Questions
What is JWT authentication in Go?
JWT authentication uses signed JSON Web Tokens to identify authenticated users and protect API endpoints in a Go application.
Which JWT package can I use in Go?
A commonly used library is:
github.com/golang-jwt/jwt/v5
How should passwords be stored?
Store password hashes, not plain-text passwords.
bcrypt is one common option in Go:
golang.org/x/crypto/bcrypt
Where should I store the JWT secret?
Store it in environment variables or a dedicated secrets-management service.
Do not commit the secret to Git.
How does the client send a JWT?
Normally:
Authorization: Bearer TOKEN
What happens when a JWT expires?
The API should reject it.
If your application supports refresh tokens, the client can use a valid refresh token to obtain a new access token.
Should access tokens expire?
Yes.
Short-lived access tokens reduce the risk if a token is stolen.
Is JWT encrypted?
Not usually.
Standard signed JWT payloads can generally be decoded and read.
The signature protects integrity and authenticity, not confidentiality.
Can JWT contain a user role?
Yes.
For example:
{
"user_id": 15,
"role": "admin"
}
But role changes and revocation strategy should be considered carefully.
What is the difference between authentication and authorization?
Authentication determines who the user is.
Authorization determines what that authenticated user is allowed to do.
Should I store JWTs in a database?
Access JWTs often do not need to be stored.
Refresh tokens or sessions are commonly tracked server-side when logout, rotation, revocation, or device management is required.
Can Go JWT authentication work with PostgreSQL and MySQL?
Yes.
You typically store user accounts and password hashes in the database, verify credentials during login, and then generate JWTs.
Is JWT good for Go REST APIs?
Yes, JWT can work well for REST APIs when it is implemented with proper token expiry, password hashing, signature validation, refresh-token security, and HTTPS.
Conclusion
JWT authentication gives a Go backend a way to identify users and protect API endpoints.
The basic workflow is:
Register
↓
Hash Password
↓
Store User
↓
Login
↓
Verify Password
↓
Generate JWT
↓
Client Sends Bearer Token
↓
Validate JWT
↓
Access Protected Route
The most important concepts to understand are:
bcrypt password hashing
JWT claims
JWT signing
Token expiration
Bearer authentication
Middleware
Authorization
Refresh tokens
Token revocation
Secure secret management
A basic Go JWT system can be created quickly, but production authentication requires more than simply generating a token.
You should also handle secure password storage, HTTPS, login rate limiting, token expiry, refresh-token rotation, logout, session revocation, database integration, error handling, and authorization.
Once you understand these concepts, you can build complete authentication systems for Go REST APIs, mobile application backends, web applications, SaaS platforms, marketplaces, and microservices.
