Custom Routes

Configure custom routes in your application to extend the library's auth endpoints.

Extending Default Auth Routes with Custom Endpoints

GoBetterAuth allows you to add custom API endpoints to the default authentication routes. This is useful for adding features or handling custom logic within your authentication flow.

How It Works

You can register custom routes using the RegisterRoute method. Each route is defined by a CustomRoute struct:

import (
  "net/http"

  gobetterauthconfig "github.com/GoBetterAuth/go-better-auth/config"
  gobetterauthmodels "github.com/GoBetterAuth/go-better-auth/models"
)

type CustomRouteMiddleware func(http.Handler) http.Handler

type CustomRouteHandler func(config *gobetterauthmodels.Config) http.Handler

type CustomRoute struct {
  Method     string
  Path       string
  Middleware []CustomRouteMiddleware
  Handler    CustomRouteHandler
}

Method: The HTTP method (e.g., GET, POST).
Path: The endpoint path (relative to /api/auth/).
Handler: A function that returns an http.Handler, with access to your auth config.

Example: Adding Custom Endpoints

1. GET `/api/auth/example`

Returns a message containing your app name.

import (
  "encoding/json"
  "fmt"
  "net/http"

  gobetterauth "github.com/GoBetterAuth/go-better-auth"
  gobetterauthconfig "github.com/GoBetterAuth/go-better-auth/config"
  gobetterauthmodels "github.com/GoBetterAuth/go-better-auth/models"
)

config := gobetterauthconfig.NewConfig(/*...*/)

goBetterAuth := gobetterauth.New(config)

goBetterAuth.RegisterRoute(gobetterauthmodels.CustomRoute{
  Method: "GET",
  Path:   "example",
  Middleware: []gobetterauthmodels.CustomRouteMiddleware{
    goBetterAuth.AuthMiddleware(),
  },
  Handler: func(config *gobetterauthmodels.Config) http.Handler {
    handler := http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
      w.Header().Set("Content-Type", "application/json")
      w.WriteHeader(http.StatusOK)
      json.NewEncoder(w).Encode(map[string]any{
        "message": fmt.Sprintf("App name: %s", config.AppName),
      })
    })
    // Apply authentication middleware
    return handler
  },
})

2. POST `/api/auth/send-message`

Accepts a JSON body and returns it in the response.

import (
  "encoding/json"
  "fmt"
  "net/http"

  gobetterauth "github.com/GoBetterAuth/go-better-auth"
  gobetterauthconfig "github.com/GoBetterAuth/go-better-auth/config"
  gobetterauthmodels "github.com/GoBetterAuth/go-better-auth/models"
)

config := gobetterauthconfig.NewConfig(/*...*/)

goBetterAuth := gobetterauth.New(config)

goBetterAuth.RegisterRoute(gobetterauthmodels.CustomRoute{
  Method: "POST",
  Path:   "send-message",
  Middleware: []gobetterauthmodels.CustomRouteMiddleware{
    goBetterAuth.AuthMiddleware(),
  },
  Handler: func(config *gobetterauthmodels.Config) http.Handler {
    handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
      var body map[string]any
      if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusBadRequest)
        json.NewEncoder(w).Encode(map[string]any{
          "error": "Invalid JSON body",
        })
        return
      }

      w.Header().Set("Content-Type", "application/json")
      w.WriteHeader(http.StatusOK)
      json.NewEncoder(w).Encode(map[string]any{
        "message": fmt.Sprintf("%s: data received", config.AppName),
        "data":    body,
      })
    })
    return handler
  },
})

Step-by-Step Guide

Define your custom route using the CustomRoute struct.
Implement the handler function. You can access the auth config and use any middleware (e.g. AuthMiddleware).
Register the route with goBetterAuth.RegisterRoute(...).
Your endpoint will be available at /api/auth/{path} (e.g. /api/auth/get-message).

Notes

All custom routes are protected by the authentication middleware by default.
You can add as many custom routes as needed.
Use the config object to access app-specific settings or secrets.