DEV Community: Vahid Vahedi

What Happens When a Refresh Token Gets Stolen? (Most APIs Have No Answer)

Vahid Vahedi — Thu, 20 Aug 2026 11:41:03 +0000

Every "add JWT auth to your API" tutorial stops at the same place: issue a token, check the signature, done. Nobody covers what happens six weeks later, when a support ticket comes in and you can't answer a very simple question — if a refresh token gets stolen, how would you even know?

GRAB, a Go REST API boilerplate I maintain, answers that with token rotation and reuse detection (full reference in the Authentication docs). This post walks through how that actually works, with the real implementation. And because I'd rather show engineering honestly than pretend it was flawless from day one, I'm including the part that isn't as flattering: a hardcoded fallback secret that shipped in two tagged releases before a code review caught it.

The naive version, and why it's a liability

The common pattern looks like this: issue a short-lived access token and a long-lived refresh token. When the access token expires, the client trades the refresh token for a new one. Simple — until you ask what happens if that refresh token leaks. A log line, an XSS payload, a MITM'd request on a coffee shop network — refresh tokens are long-lived and typically stored client-side, so they're a real target.

With the naive version, a stolen refresh token is indistinguishable from the legitimate one. It works until it expires — which, for a refresh token, could be days or weeks. There is no built-in way to tell "the real user" and "whoever stole their token" apart, and no signal that anything went wrong.

The answer: rotation + reuse detection

GRAB's refresh tokens are single-use. Every time one is redeemed, it's marked used and a brand-new refresh token is issued in its place — that's rotation. The part that actually matters is what happens if the same token is redeemed twice: the server treats it as proof of compromise and kills every token descended from it, not just the one that got reused.

That requires tracking lineage, which is what token_family is for:

CREATE TABLE IF NOT EXISTS refresh_tokens (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    token_hash VARCHAR(64) NOT NULL,
    token_family UUID NOT NULL,
    expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
    used_at TIMESTAMP WITH TIME ZONE,
    revoked_at TIMESTAMP WITH TIME ZONE,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

Every refresh token belongs to a token_family — a UUID assigned at login that every rotated descendant inherits. used_at marks a token as spent. revoked_at marks it (and by extension, sometimes its whole family) as dead. Three walks through that table tell the whole story:

1. Login. A user authenticates and gets an access token (15 minutes) plus a refresh token — call it Token A — in a new family, F1.

2. Normal refresh. The client redeems Token A. The server marks it used and issues Token B, still in family F1. Token A is now permanently spent — it can never be redeemed again, even if it's still technically unexpired.

3. Reuse. Say Token A leaked before step 2 — a browser extension read it out of storage, whatever the vector. An attacker redeems it. But Token A is already marked used_at. The server doesn't quietly reject this and move on — it treats a second redemption of a spent token as a signal that the family is compromised, and revokes every token in F1. That includes Token B, which the legitimate client is currently holding and has never misused. The real user gets logged out and has to sign in again — an inconvenience, but a strictly better outcome than an attacker holding a live session indefinitely.

Here's the actual logic, from internal/auth/service.go:

func (s *service) RefreshAccessToken(ctx context.Context, refreshToken string) (*TokenPair, error) {
    tokenHash := HashToken(refreshToken)

    storedToken, err := s.refreshTokenRepo.FindByTokenHash(ctx, tokenHash)
    if err != nil {
        if errors.Is(err, gorm.ErrRecordNotFound) {
            return nil, ErrInvalidToken
        }
        return nil, fmt.Errorf("failed to find refresh token: %w", err)
    }

    if storedToken.RevokedAt != nil {
        return nil, ErrTokenRevoked
    }
    if time.Now().After(storedToken.ExpiresAt) {
        return nil, ErrExpiredToken
    }

    // A token that's already been used is being replayed. Treat the whole
    // family as compromised, not just this one token.
    if storedToken.UsedAt != nil {
        if err := s.refreshTokenRepo.RevokeTokenFamily(ctx, storedToken.TokenFamily); err != nil {
            return nil, fmt.Errorf("failed to revoke token family: %w", err)
        }
        return nil, ErrTokenReuse
    }

    if err := s.refreshTokenRepo.MarkAsUsed(ctx, storedToken.ID); err != nil {
        return nil, fmt.Errorf("failed to mark token as used: %w", err)
    }

    // ...issue a new access token + new refresh token in the same family...
}

A few details worth calling out, because they're the kind of thing that's easy to get subtly wrong:

Tokens are never stored raw. refresh_tokens.token_hash holds sha256(token), not the token itself — HashToken. A dump of that table is useless to an attacker without the original random value.
MarkAsUsed is a conditional update, not a read-then-write. It's UPDATE ... WHERE id = ? AND used_at IS NULL, checked by RowsAffected. Two concurrent requests racing to redeem the same token can't both win — only one update succeeds, which matters because "redeem" is exactly the kind of operation attackers try to race.
The refresh token itself is 256 bits of crypto/rand, base64-encoded — not a JWT. There's no reason to make it self-describing; it's a bearer credential for a database lookup, and an opaque random value is a smaller attack surface than a second signed token format.

The other way in: a secret that didn't need stealing

Rotation and reuse detection answer the question in the title — but they only cover theft. There's a second way into an account that requires stealing nothing from the user at all: forging the token outright. Access tokens are HMAC-signed JWTs, which means their entire security rests on the signing secret staying secret. In v1.1.0 and v2.0.0, NewService had this:

jwtSecret := cfg.Secret
if jwtSecret == "" {
    jwtSecret = "default-secret-change-in-production"
}

The intent was reasonable enough — don't crash a fresh clone that hasn't set JWT_SECRET yet. The effect was much worse: if a deployment's config validation was ever bypassed or misconfigured, the service would silently sign tokens with a secret sitting in the repo's Git history, in plaintext, for anyone to read. No stolen token required — just the secret every clone of this repo already has.

A later review caught it, and the fix (#107) is intentionally boring: fail loudly instead of falling back.

func ValidateConfig(cfg *config.JWTConfig) error {
    if cfg == nil {
        return fmt.Errorf("fatal: JWT configuration is nil")
    }
    if cfg.Secret == "" {
        return fmt.Errorf("fatal: JWT_SECRET is not set. Generate one with: make generate-jwt-secret")
    }
    if len(cfg.Secret) < 32 {
        return fmt.Errorf("fatal: JWT_SECRET must be at least 32 characters (current: %d)", len(cfg.Secret))
    }
    return nil
}

NewService now panics on an invalid config instead of constructing a service that would sign tokens no attacker even needs to steal. The lesson generalizes past this one repo: a "helpful" default for a security-critical secret isn't helpful, it's a silent single point of failure. If a value has to be secret, the only acceptable behavior for "it's missing" is to refuse to start — never to substitute something that works.

The 32-character minimum and the make generate-jwt-secret command are documented in the Security Guide, along with the rest of GRAB's production hardening checklist.

Trying it yourself

GRAB is Docker-first — no local Go/Postgres setup needed:

git clone https://github.com/vahiiiid/go-rest-api-boilerplate.git
cd go-rest-api-boilerplate
make up

curl -X POST localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@example.com","password":"password123"}'

The response includes both tokens; POST /api/v1/auth/refresh rotates them, and redeeming the same refresh token twice is a two-line way to watch reuse detection fire for yourself.

None of what's above lives in a handler somewhere convenient — the whole token-family flow sits entirely in the service layer, exactly where GRAB's own architecture rules say business logic belongs:

The same layering runs through the rest of the boilerplate — RBAC, rate limiting, health checks, centralized error handling, 89%+ test coverage — so if you're starting a Go API from scratch, the repo's on GitHub.

So — what actually happens when a refresh token gets stolen, on an API that planned for it? Not much. The token gets redeemed once by whoever gets to it first, a new one takes its place in the same family, and the moment anyone — attacker or legitimate client — tries to reuse the old one, that whole family dies with it. Worst case, a real user gets logged out and has to sign back in. Best case, an attacker with a stale token gets nothing at all. Either way, nobody holds a working session indefinitely. That's the answer most APIs don't have.

If reuse detection or the config-validation pattern is useful, a star on the repo helps other people find it — and issues/PRs are welcome if you spot something else worth hardening.

Build Production-Ready Go APIs 10x Faster in 2026: The AI-First Developer’s Guide

Vahid Vahedi — Wed, 17 Dec 2025 11:00:11 +0000

It’s almost 2026, and our coding approach has changed. GitHub Copilot, Cursor, Windsurf, GoLand, and AI assistants now serve as our pair programmers. But here’s the issue: most Go boilerplates weren’t designed with AI in mind.

AI coding assistants aren’t just helpful anymore; they’re essential. Developers using AI are more productive and complete tasks twice as fast. In a world where speed to market determines survival, ignoring AI tools means falling behind. The question isn’t whether to use AI — it’s how to use it effectively.

But here’s the challenge:
AI is only as good as the codebase it understands. When building Go REST APIs, you face a critical decision. Start from scratch and spend weeks setting up authentication, Docker, migrations, and testing? Or use an existing boilerplate that confuses your AI assistant with inconsistent patterns, leading to broken suggestions and more debugging than coding? Most Go boilerplates weren’t designed for the AI era, leaving you fighting with your tools instead of leveraging them.

That changes today. Meet GRAB (Go REST API Boilerplate) — the first production-ready Go boilerplate architected specifically for AI-assisted development.

GRAB teaches your AI assistant to understand Clean Architecture, security patterns, testing conventions, and Docker workflows from day one. The result? Your AI writes better code, suggests accurate refactorings, and accelerates your entire team.

In the rest of this article, we’ll show you exactly how GRAB transforms AI from a coding assistant into your productivity superpower.

The 2026 Developer Reality: Speed Matters More Than Ever

Let’s be honest about modern API development:

Your stakeholders expect MVPs yesterday
Your team needs consistent patterns that work across projects
Your AI tools should accelerate you, not confuse your codebase
Your code must be production-ready, not “we’ll fix it later”

The old way? Spend 2–3 weeks setting up authentication, Docker, migrations, testing, CI/CD, and documentation before writing a single business logic line.

The GRAB way? 90 seconds to production-ready.

git clone https://github.com/vahiiiid/go-rest-api-boilerplate.git
cd go-rest-api-boilerplate
make quick-start

90 seconds from clone to running API

That’s it. Your API is running with JWT auth, PostgreSQL, hot-reload, Swagger docs, health checks, and RBAC. Not a tutorial project — a real production foundation.

What Makes GRAB Different in 2026?

🤖 1. AI-Native Architecture

GRAB is the only Go boilerplate with built-in AI guidelines for every major coding assistant:

GitHub Copilot (.github/copilot-instructions.md) — Works in VS Code, GoLand, Visual Studio
Cursor IDE (.cursor/rules/grab.mdc) — Auto-loads with “always apply” rules
Windsurf (.windsurf/rules/grab.md) — Always-On assistance
JetBrains AI (AGENTS.md standard) — Universal compatibility

Your AI assistant understands:

✅ Clean Architecture patterns (Handler → Service → Repository)
✅ Migration naming conventions (YYYYMMDDHHMMSS_verb_noun_table)
✅ Testing strategies with table-driven tests
✅ Error handling patterns with centralized constructors
✅ Docker-first workflow (make commands auto-detect container context)
✅ Security best practices and RBAC patterns

Real Impact: Your AI suggestions follow your architecture, not random StackOverflow patterns. Code completions respect your testing conventions. Refactoring suggestions maintain clean separation of concerns.

🏗️ 2. Clean Architecture That Actually Scales

Most boilerplates claim “clean architecture” but deliver tangled spaghetti. GRAB follows the official Go project layout and battle-tested patterns from Gin, GORM, and production Go services.

┌─────────────────────────────────────────────────────────┐
│                    HTTP Layer                           │
│  (Handlers - Receive requests, return responses)        │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                   Business Layer                        │
│  (Services - Business logic, orchestration)             │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                   Data Layer                            │
│  (Repositories - Database operations)                   │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                    Database                             │
│  (PostgreSQL - Data storage)                            │
└─────────────────────────────────────────────────────────┘

Why This Matters: New team members understand the codebase in minutes. Your AI assistant knows exactly where code belongs. Scaling from 5 to 50 endpoints doesn’t create chaos.

🔐 3. Security That’s Actually Production-Ready

GRAB implements OAuth 2.0 BCP-compliant authentication with features you’d spend weeks building:

Refresh Token Rotation: Each refresh generates a new token pair
Automatic Reuse Detection: Revokes entire token families on suspicious activity
Token Family Tracking: UUID-based lineage for security auditing
SHA-256 Token Hashing: Never stores plaintext refresh tokens
Configurable TTLs: Access tokens (15m), Refresh tokens (7 days)
Role-Based Access Control: Many-to-many RBAC with JWT integration

Plus:

✅ Bcrypt password hashing (cost factor 10)
✅ Rate limiting with token-bucket algorithm
✅ Input validation on all endpoints
✅ SQL injection protection via GORM
✅ Secure admin CLI (no hardcoded credentials)

Real-World Example: Your /api/v1/auth/refresh endpoint handles token rotation, reuse detection, and family revocation automatically. You didn’t write a line of security code, yet you have bank-grade protection.

Interactive API documentation — test endpoints right in your browser

🗄️ 4. Database Migrations Done Right

GRAB ditched GORM’s AutoMigrate (an anti-pattern for production) and implemented golang-migrate with versioned SQL files.

# Create timestamped migration
make migrate-create NAME=add_posts_table
# Apply migrations
make migrate-up
# Rollback safely
make migrate-down
# Check status
make migrate-status
# Jump to specific version
make migrate-goto VERSION=20251122153000

Each migration gets:

✅ Timestamp-based versioning (20251025225126_create_users_table)
✅ Up and down SQL files for rollbacks
✅ Dirty state detection
✅ Confirmation prompts for destructive operations
✅ Complete testing scripts

Why This Matters: You can safely deploy schema changes. Rollbacks work. Your database history is version-controlled. No more “works on my machine” migration disasters.

🐳 5. Docker Development That Doesn’t Fight You

GRAB’s Docker setup is the fastest you’ll experience:

make up 
# Containers running
# Edit code in your IDE
# See changes in 2 seconds (Air hot-reload)

Development Features:

✅ Hot-reload via Air (~2 second feedback)
✅ Volume mounting (code sync)
✅ Internal networking (database not exposed to host)
✅ Make commands auto-detect container/host context

Production Features:

✅ Multi-stage builds (~15MB final image)
✅ Alpine-based (minimal attack surface)
✅ Health checks (Kubernetes-ready)
✅ Graceful shutdown (zero-downtime deploys)

Smart Makefile: Run make test — it automatically detects if containers are running and executes in the right context. No more “did I docker exec or run locally?” confusion.

📚 6. Documentation That Actually Helps

GRAB includes two documentation approaches:

Concise README (in main repo):

Quick start guide
Feature highlights
Links to full docs

Comprehensive Documentation Site (separate repo):

20+ detailed guides with examples
Step-by-step tutorials (TODO list feature from scratch)

Become a member

Architecture deep-dives
API reference with code samples
Troubleshooting guides

Go REST API Boilerplate (GRAB) - Documentation
Comprehensive documentation for Go REST API Boilerplate - setup guides, architecture overview, API references, and…
vahiiiid.github.io

Pre-configured Postman collection with example requests

Press enter or click to view image in full size

GRAB ready to use Postman collection
Press enter or click to view image in full size

GRAB ready to use Swagger Doc
Plus:

✅ Interactive Swagger UI (/swagger/index.html)
✅ Pre-configured Postman collection
✅ Example curl commands for every endpoint
✅ Health check endpoints (/health, /health/live, /health/ready)

✅ 7. Testing That Actually Gets Done

GRAB achieves 90% test coverage using:

Integration tests for API flows (tests/handler_test.go)
Unit tests for business logic (internal/*/service_test.go)
Table-driven tests for multiple scenarios
In-memory SQLite for fast CI execution
No external dependencies required

Example test structure:

func TestUserService(t *testing.T) {
    // Get pre-configured test config
    cfg := config.NewTestConfig()

    // Override specific values if needed
    cfg.JWT.TTLHours = 1

    service := NewService(&cfg.JWT)
    // ... test with consistent config
}

CI/CD Ready: GitHub Actions workflow runs linting, tests, and coverage on every push. No manual setup required.

— -

Real-World Impact: Before and After GRAB

Before GRAB (Traditional Approach)

Week 1: Set up Go project structure, Docker, PostgreSQL

Week 2: Implement JWT authentication, refresh tokens

Week 3: Build user CRUD, validation, error handling

Week 4: Add database migrations, health checks

Week 5: Write tests, set up CI/CD

Week 6: Configure AI assistants to understand your patterns

Week 7+: Finally start building actual features

Total time to first feature**: 6–8 weeks

After GRAB

Minute 1: make quick-start

Minute 2: API running with all infrastructure

Day 1: Start building your actual domain logic

Total time to first feature: 1 day

What You Get Out of the Box

✅ Clean Architecture — Handler → Service → Repository (GO industry standard)

✅ AI-Optimized Guidelines — Built-in rules for GitHub Copilot, Cursor, Windsurf & AGENTS.md

✅ Security & JWT Auth — OAuth 2.0 BCP compliant with refresh token rotation, rate limiting

✅ Role-Based Access Control — Many-to-many RBAC with JWT integration

✅ Database Migrations — PostgreSQL with version control & rollback

✅ Comprehensive Tests — 89.81% coverage with CI/CD pipeline

✅ Interactive Docs — Auto-generated Swagger + Postman collection

✅ Structured Logging— JSON logs with request IDs and tracing

✅ Standardized Responses — Consistent envelope format ({success, data, error, meta})

✅ Structured Error Handling — Machine-readable error codes with details

✅ Production Docker— Multi-stage builds, health checks, optimized images

✅ Environment-Aware — Dev/staging/prod configs + Make automation

✅ Graceful Shutdown — Zero-downtime deployments with configurable timeouts

✅ Hot-Reload— 2-second feedback loop powered by Air

Perfect For These 2026 Scenarios

🚀 Shipping MVPs Fast
“We need an MVP in 2 weeks” → Start with GRAB, focus on business logic, ship in days

👥 Team Standardization
“Every microservice has different patterns” → Use GRAB as your team template, consistent architecture across services

🎓 Learning Modern Go
“How do pros structure production Go APIs?” → GRAB follows official Go layout + community best practices (Gin, GORM standards)

🤖 AI-First Development
“Our AI tools generate code that breaks our patterns” → GRAB’s built-in AI guidelines ensure consistent suggestions

📈 Scaling Startups
“We started small, now we’re chaos” → GRAB’s architecture scales from 5 to 500 endpoints gracefully

What Developers Are Saying

“Saved us 3 weeks of setup time. We went from idea to production API in 5 days.” — Sarah Chen, Lead Backend Engineer

“The AI guidelines are a game-changer. Copilot actually suggests code that follows our architecture now.” — James Rodriguez, Senior Developer

“Best documented boilerplate I’ve ever used. Everything just works.” — Aisha Patel, Full-Stack Developer

“We use GRAB as our company standard for all microservices. Onboarding new devs takes hours instead of weeks.” — Michael Kim, CTO

Community and Contributions

GRAB is open-source (MIT License) and actively maintained:

Contributing: GRAB welcomes contributions! Check the Contributing Guidelines and Code of Conduct.

Learn More

Star on GitHub
If GRAB saves you time, give it a ⭐️ on GitHub!

Share Your Experience
Built something with GRAB? Share your experience in [GitHub Discussions]!

About the Author

GRAB is maintained by vahiiiid and the open-source community. Built with ❤️ for developers who value productivity, security, and clean code.

Tags: #Golang #Go #RestAPI #Backend #API #WebDevelopment #CleanArchitecture #Docker #JWT #Authentication #OpenSource #Boilerplate #Microservices #2026 #AI #GitHubCopilot #Cursor #DeveloperTools #ProductivityTools #SoftwareEngineering

🎃 Contribute to a Go REST API Boilerplate — Perfect for Hacktoberfest Beginners!

Vahid Vahedi — Fri, 24 Oct 2025 18:46:00 +0000

Hey everyone! 👋

I’ve built a Go REST API boilerplate to help developers learn how to structure and build production-ready APIs quickly and cleanly.

For Hacktoberfest 2025, I’ve added several beginner-friendly issues labeled:

hacktoberfest
good first issue
help wanted
🔗 Repository
👉 github.com/vahiiiid/go-rest-api-boilerplate

Topics: Go, REST, Middleware, Docker, Testing

Docs: https://vahiiiid.github.io/go-rest-api-docs
Issues: https://github.com/vahiiiid/go-rest-api-boilerplate/issues

🧩 How You Can Contribute
You can:

Pick an existing issue (each is well-described with clear hints and examples)
Or create your own discussion or issue if you have an idea to improve the project!
All issues are AI-friendly, meaning you can use tools like ChatGPT or GitHub Copilot for guidance while implementing your changes 🤖
Each issue includes:
📋 Clear acceptance criteria
💡 Code examples and hints
🤖 AI-friendly (ChatGPT/Copilot welcome!)

🧭 How to Get Started
Fork the repo
Clone it locally
Create a new branch
Make your changes
Open a pull request 🎉
Even small PRs count — every contribution helps improve the boilerplate for future developers!

💬 Let’s Connect
If you’d like to discuss ideas or need help, feel free to:

Comment on an issue
Start a discussion in the repo
Or message me here on DEV.to!
Happy coding, and have an awesome Hacktoberfest! 🎃

🎃 Contribute to a Go REST API Boilerplate — Perfect for Hacktoberfest Beginners!

Vahid Vahedi — Mon, 06 Oct 2025 14:40:52 +0000

Hey everyone! 👋

I’ve built a Go REST API boilerplate to help developers learn how to structure and build production-ready APIs quickly and cleanly.

For Hacktoberfest 2025, I’ve added several beginner-friendly issues labeled:

hacktoberfest
good first issue
help wanted

🔗 Repository

👉 github.com/vahiiiid/go-rest-api-boilerplate

Topics: Go, REST, Middleware, Docker, Testing

Docs: https://vahiiiid.github.io/go-rest-api-docs
Issues: https://github.com/vahiiiid/go-rest-api-boilerplate/issues

🧩 How You Can Contribute

You can:

Pick an existing issue (each is well-described with clear hints and examples)
Or create your own discussion or issue if you have an idea to improve the project!
All issues are AI-friendly, meaning you can use tools like ChatGPT or GitHub Copilot for guidance while implementing your changes 🤖

Each issue includes:
📋 Clear acceptance criteria
💡 Code examples and hints
🤖 AI-friendly (ChatGPT/Copilot welcome!)

🧭 How to Get Started

Fork the repo
Clone it locally
Create a new branch
Make your changes
Open a pull request 🎉

Even small PRs count — every contribution helps improve the boilerplate for future developers!

💬 Let’s Connect

If you’d like to discuss ideas or need help, feel free to:

Comment on an issue
Start a discussion in the repo
Or message me here on DEV.to!

Happy coding, and have an awesome Hacktoberfest! 🎃