Skip to main content
Custom API endpoints let you add your own HTTP endpoints to the Orchestrator. Use custom APIs to build health checks, webhook receivers, token exchange endpoints, or any custom endpoint that needs access to sessions, caches, and other Orchestrator services.

​
Request Lifecycle

Unlike other hooks that run during request processing, serveSE runs once when the Orchestrator starts up. Your extension registers HTTP route handlers that then execute whenever a matching request arrives.

​
Hooks

​
serveSE

Register custom HTTP endpoints on the Orchestrator. This hook runs at startup and gives you access to the router to define your own API routes. Use this to implement custom REST endpoints, webhook receivers, or internal service APIs. Signature: 
func ServeAPI(api orchestrator.Orchestrator) error
App types: Top-level apis[] Config location: apis[].serveSE Parameters:
ParameterTypeDescription
apiorchestrator.OrchestratorAccess to sessions, caches, secrets, logging, router, and other Orchestrator services
Returns: error — return nil on success, or an error if the API handler setup fails.

​
Configuration

Custom API endpoints are defined under the apis top-level key in the deployment configuration.
maverics.yaml
apis:
  - name: my-custom-endpoint
    serveSE:
      funcName: ServeAPI
      file: /path/to/api-handler.go

​
Field Reference

KeyTypeDefaultRequiredDescription
apis[].namestring—YesUnique name for the API endpoint
apis[].serveSEServiceExtension—YesService extension that handles requests to this endpoint
The serveSE field accepts the standard ServiceExtension object (funcName, code/file, metadata, goPath, allowedProtectedPackages).

​
Validation Rules

  • Each name must be unique across all apis[] entries
  • The serveSE field is required — an API endpoint without a handler is invalid

​
Example

A custom health check endpoint and a user info endpoint:
maverics.yaml
apis:
  - name: custom-health
    serveSE:
      funcName: HealthCheck
      file: /etc/maverics/extensions/health-check.go
      metadata:
        backendURL: "https://backend.example.com/health"

  - name: user-info
    serveSE:
      funcName: GetUserInfo
      file: /etc/maverics/extensions/user-info.go
Multiple custom APIs can be defined, each with its own service extension handler.

Service Extensions Overview

Configuration, SDK reference, and best practices

Applications

Application configuration for proxy, OIDC, and SAML apps