Custom Routes

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

Adding Custom Routes

Authula allows you to add custom API endpoints to your application. This is useful for adding features or handling custom logic.

How It Works

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

import (
  "net/http"

  authulaconfig "github.com/Authula/authula/config"
  authulamodels "github.com/Authula/authula/models"
)

type Route struct {
  Method     string
  Path       string
  Handler    http.Handler
  Middleware []func(http.Handler) http.Handler
  // Metadata holds route-specific metadata, including plugin IDs ("plugins"),
  // custom tags, and plugin-specific attributes for conditional hook execution.
  Metadata map[string]any
}

Method: The HTTP method (e.g., GET, POST).
Path: The endpoint path.
Handler: An http.Handler for the route.
Middleware: A list of middleware functions to apply to the route.
Metadata: Additional metadata for the route.

Example: Adding Custom Endpoints

1. GET `/api/auth/example`

Returns a message containing your app name.

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

  authula "github.com/Authula/authula"
  authulaconfig "github.com/Authula/authula/config"
  authulamodels "github.com/Authula/authula/models"
)

config := authulaconfig.NewConfig(/*...*/)
auth := authula.New(config)

auth.RegisterCustomRoute(authulamodels.Route{
  Method: "GET",
  Path:   "example",
  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": "App name: MyApp",
    })
  }),
  // Optional
  // Middleware: []func(http.Handler) http.Handler{},
  // Optional
  // Metadata: map[string]any{},
})

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

Accepts a JSON body and returns it in the response.

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

  authula "github.com/Authula/authula"
  authulaconfig "github.com/Authula/authula/config"
  authulamodels "github.com/Authula/authula/models"
)

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

auth := authula.New(config)

auth.RegisterCustomRoute(authulamodels.Route{
  Method: "POST",
  Path:   "send-message",
  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": "Data received",
      "data":    body,
    })
  }),
  // Middleware: []func(http.Handler) http.Handler{},
  Metadata: map[string]any{
    "plugins": []string{
      "csrf.protect",
    },
  },
})

3. GET `/api/health`

Health check endpoint.

// Health check endpoint
auth.RegisterCustomRoute(authulamodels.Route{
  Method:   "GET",
  Path:     "/api/health",
  Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusAccepted)
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(map[string]any{
      "status": "ok",
    })
  }),
})

When handling requests in your custom routes, you can access the custom RequestContext which provides a structured abstraction for passing context through request lifecycle hooks. It encapsulates all request-related information and provides control mechanisms for hooks and is also accessible within routes. It is actually advised to use the RequestContext as it comes with handy utility methods and also is the main request object being passed through the lifecycle of the http request/response which also means you can make modifications to it and it will persist throughout the lifecycle. For example, a hook may have already modified some data in the RequestContext, you can then access that modified data in your custom route handler.

auth.RegisterCustomRoute(authulamodels.Route{
  Method:   "GET",
  Path:     "/api/custom",
  Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    // You can access it like so:
    reqCtx, _ := authulamodels.GetRequestContext(r.Context())
    reqCtx.SetJSONResponse(http.StatusOK, map[string]any{
      "status": "ok",
    })
  }),
})

Step-by-Step Guide

Define your custom route using the Route struct.
Implement the handler function as an http.Handler.
Register the route with auth.RegisterCustomRoute(...).
Your endpoint will be available at the specified path.

Notes

Custom routes are not protected by authentication by default; implement authentication via middleware or metadata by adding the plugins you want with their capabilities.
You can add as many custom routes as needed.