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 `/health`

Health check endpoint.

import (
  "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:   "/health",
  Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    reqCtx, _ := authulamodels.GetRequestContext(ctx)

    reqCtx.SetJSONResponse(http.StatusOK, map[string]any{
      "status": "ok",
    })
  }),
  // Optional
  // Middleware: []func(http.Handler) http.Handler{},
  // Optional
  // Metadata: map[string]any{},
})

2. POST `/send-message`

Accepts a JSON body and returns it in the response.

import (
  "net/http"

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

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

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

auth.RegisterCustomRoute(authulamodels.Route{
  Method: "POST",
  Path:   "/send-message",
  Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    reqCtx, _ := authulamodels.GetRequestContext(ctx)

    var request SendMessageRequest
    if err := authulainternalutils.ParseJSON(r, &request); err != nil {
      reqCtx.SetJSONResponse(http.StatusUnprocessableEntity, map[string]any{
        "message": "invalid request body",
      })
      reqCtx.Handled = true
      return
    }

    reqCtx.SetJSONResponse(http.StatusOK, map[string]any{
      "message": "Data received",
      "data":    request,
    })
  }),
  // Middleware: []func(http.Handler) http.Handler{},
  Metadata: map[string]any{
    "plugins": []string{
      "csrf.protect",
    },
  },
})

When handling requests in custom routes, you can access the custom RequestContext to pass structured request data through the request lifecycle. It encapsulates request-related information, provides hook control mechanisms, and is available inside route handlers.

Using RequestContext is recommended because it includes useful utility methods and is the main request object used throughout the HTTP request/response lifecycle. Changes made to it persist for the duration of the request, so if a hook has already modified data in RequestContext, your custom route can access the updated values.

import (
  "net/http"

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

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:
    ctx := r.Context()
    reqCtx, _ := authulamodels.GetRequestContext(ctx)

    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.