auth_apis

README

auth_apis

A weedbox module that registers REST API endpoints for authentication. Provides Gin HTTP handlers for login, token refresh, and logout.

Overview

On startup, this module registers authentication routes under /apis/v1/auth on the HTTP server. All endpoints are public (permission "*") since they handle unauthenticated or token-based access.

Dependencies

Dependency	Source	Description
http_server.HTTPServer	common-modules	Gin HTTP server for route registration
auth.AuthManager	user-modules/auth	Authentication business logic

Module Registration

auth_apis.Module("auth_apis")

Endpoints

All endpoints are prefixed with /apis/v1/auth.

Login

POST /apis/v1/auth/login

Permission: Public (no authentication required)

Authenticate with username or email and password. Returns a JWT access token and a refresh token.

Request Body:

{
  "identifier": "admin",
  "password": "1qaz@WSX"
}

Field	Required	Description
identifier	Yes	Username or email
password	Yes	Password

Response (200):

{
  "message": "Login successful",
  "token": {
    "access_token": "eyJhbGciOi...",
    "refresh_token": "base64-encoded-token",
    "token_type": "Bearer",
    "expires_in": 900,
    "expires_at": "2025-01-01T00:15:00Z",
    "refresh_expires_at": "2025-01-08T00:00:00Z"
  },
  "user": {
    "id": "...",
    "username": "admin",
    "email": "admin@localhost",
    "display_name": "System Administrator",
    "roles": ["admin"]
  }
}

Error Responses:

Status	Condition
400	Missing or invalid request body
401	Invalid credentials
403	User account is not active
500	Internal server error

Refresh Tokens

POST /apis/v1/auth/refresh

Permission: Public

Exchange a valid refresh token for a new access token and refresh token. The old refresh token is automatically revoked (token rotation).

Request Body:

{
  "refresh_token": "base64-encoded-token"
}

Response (200):

{
  "message": "Token refreshed successfully",
  "token": {
    "access_token": "eyJhbGciOi...",
    "refresh_token": "new-base64-encoded-token",
    "token_type": "Bearer",
    "expires_in": 900,
    "expires_at": "2025-01-01T00:15:00Z",
    "refresh_expires_at": "2025-01-08T00:00:00Z"
  }
}

Error Responses:

Status	Condition
400	Missing or invalid request body
401	Invalid, expired, or revoked refresh token
403	User account is not active
500	Internal server error

Logout

POST /apis/v1/auth/logout

Permission: Public

Revoke a refresh token to end the session.

Request Body:

{
  "refresh_token": "base64-encoded-token"
}

Response (200):

{
  "message": "Logged out successfully"
}

Error Responses:

Status	Condition
400	Missing or invalid request body
404	Refresh token not found
500	Internal server error

Authentication Flow

1. Client sends POST /auth/login with credentials
2. Server validates credentials and returns access_token + refresh_token
3. Client uses access_token in Authorization header for subsequent requests
4. When access_token expires, client sends POST /auth/refresh with refresh_token
5. Server revokes old refresh_token, issues new access_token + refresh_token
6. To log out, client sends POST /auth/logout with refresh_token

Security Notes

• Token Rotation: Each refresh operation revokes the old refresh token and issues a new one. This limits the window of exposure if a refresh token is compromised.
• Public Endpoints: All auth endpoints are public by design — login requires no prior authentication, and refresh/logout validate security through the refresh token itself.
• Inactive Users: If a user's status is not active, login and refresh will be rejected with 403 Forbidden.

Documentation

Index

• Constants
• func Module(scope string) fx.Option
• type AuthAPIs
  • func (m *AuthAPIs) InitDefaultConfigs()
  • func (m *AuthAPIs) OnStart(ctx context.Context) error
  • func (m *AuthAPIs) OnStop(ctx context.Context) error
• type ErrorResponse
• type LoginRequest
• type LoginRequestBody
• type LoginResponse
• type LogoutRequest
• type LogoutRequestBody
• type LogoutResponse
• type Params
• type RefreshRequest
• type RefreshRequestBody
• type RefreshResponse
• type TokenResponse
• type UserInfo

Constants

const ModuleName = "AuthAPIs"

Functions

func Module

func Module(scope string) fx.Option

Types

type AuthAPIs

type AuthAPIs struct {
	weedbox.Module[*Params]
}

func (*AuthAPIs) InitDefaultConfigs

func (m *AuthAPIs) InitDefaultConfigs()

func (*AuthAPIs) OnStart

func (m *AuthAPIs) OnStart(ctx context.Context) error

func (*AuthAPIs) OnStop

func (m *AuthAPIs) OnStop(ctx context.Context) error

type ErrorResponse

type ErrorResponse struct {
	Error string `json:"error" example:"error message"`
}

ErrorResponse error response

type LoginRequest

type LoginRequest struct {
	Body LoginRequestBody
}

type LoginRequestBody

type LoginRequestBody struct {
	Identifier string `json:"identifier" binding:"required"` // username or email
	Password   string `json:"password" binding:"required"`
}

type LoginResponse

type LoginResponse struct {
	Message string        `json:"message"`
	Token   TokenResponse `json:"token"`
	User    *UserInfo     `json:"user,omitempty"`
}

LoginResponse login response

type LogoutRequest

type LogoutRequest struct {
	Body LogoutRequestBody
}

type LogoutRequestBody

type LogoutRequestBody struct {
	RefreshToken string `json:"refresh_token" binding:"required"`
}

type LogoutResponse

type LogoutResponse struct {
	Message string `json:"message"`
}

LogoutResponse logout response

type Params

type Params struct {
	weedbox.Params
	HTTPServer *http_server.HTTPServer
	Auth       *auth.AuthManager `name:"auth"`
}

type RefreshRequest

type RefreshRequest struct {
	Body RefreshRequestBody
}

type RefreshRequestBody

type RefreshRequestBody struct {
	RefreshToken string `json:"refresh_token" binding:"required"`
}

type RefreshResponse

type RefreshResponse struct {
	Message string        `json:"message"`
	Token   TokenResponse `json:"token"`
}

RefreshResponse refresh response

type TokenResponse

type TokenResponse struct {
	AccessToken      string    `json:"access_token"`
	RefreshToken     string    `json:"refresh_token"`
	TokenType        string    `json:"token_type"`
	ExpiresIn        int64     `json:"expires_in"`
	ExpiresAt        time.Time `json:"expires_at"`
	RefreshExpiresAt time.Time `json:"refresh_expires_at"`
}

TokenResponse contains authentication tokens

type UserInfo

type UserInfo struct {
	ID          string   `json:"id"`
	Username    string   `json:"username"`
	Email       string   `json:"email"`
	DisplayName string   `json:"display_name"`
	Roles       []string `json:"roles"`
}

UserInfo contains basic user information returned with tokens