Getting Started

Installation

go get github.com/cybergodev/jwt

Requires Go 1.25+.

Basic Usage

1. Create Processor

package main

import (
    "fmt"
    "time"

    "github.com/cybergodev/jwt"
)

func main() {
    cfg := jwt.DefaultConfig()
    cfg.SecretKey = "hmac-key-that-has-at-least-32-bytes!" // HMAC requires at least 32 bytes
    cfg.AccessTokenTTL = 15 * time.Minute
    cfg.RefreshTokenTTL = 7 * 24 * time.Hour

    processor, err := jwt.New(cfg)
    if err != nil {
        panic(err)
    }
    defer processor.Close() // Securely clear keys
}

2. Issue Token

claims := &jwt.Claims{
    UserID:   "user123",
    Username: "alice",
    Role:     "admin",
    Permissions: []string{"read", "write"},
}

// Access token (short-lived)
accessToken, err := processor.Create(claims)
if err != nil {
    panic(err)
}

// Refresh token (long-lived)
refreshToken, err := processor.CreateRefresh(claims)
if err != nil {
    panic(err)
}

3. Validate Token

parsed, valid, err := processor.Validate(accessToken)
if err != nil {
    // Handle error: expired, invalid signature, etc.
    panic(err)
}
if valid {
    fmt.Println("UserID:", parsed.UserID)
    fmt.Println("Role:", parsed.Role)
    fmt.Println("ExpiresAt:", parsed.ExpiresAt.Time)
}

4. Refresh Token

newAccessToken, err := processor.Refresh(refreshToken)
if err != nil {
    panic(err)
}
fmt.Println("New Access Token:", newAccessToken)

5. Revoke Token

// Add token to blacklist
err := processor.Revoke(accessToken)
if err != nil {
    panic(err)
}

// Check if revoked
revoked, err := processor.IsRevoked(accessToken)
if err != nil {
    panic(err)
}
fmt.Println("Revoked:", revoked) // true

More Features

The steps above cover the core token lifecycle. CyberGo JWT also provides the following features — click into each guide for detailed usage:

Feature	Description	Guide
Signing Algorithms	HMAC, RSA, RSA-PSS, ECDSA — 12 algorithms across 4 families	Signing Algorithms
Custom Claims	Define business-specific fields via the CustomClaims interface	Custom Claims
Token Refresh & Rotation	Two-tier token TTL design, reuse vs. one-time rotation strategies	Token Refresh & Rotation
Token Blacklist	Revocation, built-in memory store, and Redis custom backends	Token Blacklist
Rate Limiting	Token bucket algorithm to prevent abuse of issuance endpoints	Rate Limiting
Configuration	Issuer/audience validation, clock skew, mandatory expiration, input validation	Configuration
Error Handling	19 sentinel error categories and errors.Is matching	Error Handling
Testing & Clock Injection	FixedClock for deterministic, sleep-free time control in tests	Testing & Clock Injection

Next Steps

• Signing Algorithms — Algorithm selection and key configuration
• Token Refresh & Rotation — Two-tier tokens and rotation strategies
• Configuration — Security config and input validation
• API Reference — Complete API reference
• Basic Examples — Runnable complete examples
• Web Server Integration — Auth middleware and RBAC in practice