Admin API

optional

Under the api config option the Admin API can be configured.

The Admin API provides HTTP endpoints for managing LightHouse configuration, subordinates, trust marks, and other aspects of the federation entity at runtime.

`admin`¶

object / mapping optional

Configuration for the Admin API.

config.yaml

api:
    admin:
        enabled: true
        users_enabled: true
        port: 0

`enabled`¶

boolean true optional LH_API_ADMIN_ENABLED

Enables or disables the Admin API. When disabled, no admin endpoints are available.

config.yaml

api:
    admin:
        enabled: true

`users_enabled`¶

boolean true optional LH_API_ADMIN_USERS_ENABLED

Enables or disables user management via the Admin API. When enabled, you can create and manage admin users through the API endpoints.

config.yaml

api:
    admin:
        enabled: true
        users_enabled: true

`port`¶

integer 0 optional LH_API_ADMIN_PORT

The port for the Admin API server.

0 (default) - Serve the Admin API on the main server port alongside federation endpoints
Any other value - Serve the Admin API on a separate port

Using a separate port can be useful for:

Network isolation (Admin API only accessible from internal network)
Different firewall rules for admin vs. federation traffic
Running admin API on a non-standard port

config.yaml (same port as main server)

api:
    admin:
        enabled: true
        port: 0

config.yaml (separate port)

api:
    admin:
        enabled: true
        port: 8080

`actor_source`¶

string basic_auth optional LH_API_ADMIN_ACTOR_SOURCE

Specifies the source for extracting the actor (user identity) for audit logging in Admin API requests.

Available options:

basic_auth (default) - Extract actor from HTTP Basic Authentication username, use HTTP header as a fallback
header - Extract actor from a custom HTTP header (see actor_header), use HTTP Basic Authentication as a fallback

This is useful when running behind a reverse proxy that handles authentication and passes the authenticated user in a header.

config.yaml

api:
    admin:
        enabled: true
        actor_source: basic_auth

config.yaml (header-based authentication)

api:
    admin:
        enabled: true
        actor_source: header
        actor_header: X-Authenticated-User

`actor_header`¶

string X-Actor optional LH_API_ADMIN_ACTOR_HEADER

The HTTP header name to use for extracting the actor when actor_source is set to header or both.

This allows integration with reverse proxies or identity-aware proxies that authenticate users and pass their identity in a custom header.

config.yaml

api:
    admin:
        enabled: true
        actor_source: header
        actor_header: X-Authenticated-User

`password_hashing`¶

object / mapping optional

Configuration for Argon2id password hashing used for admin user passwords.

Note

These settings affect how admin user passwords are hashed. The defaults provide a good balance of security and performance. Only change these if you have specific requirements.

config.yaml

api:
    admin:
        enabled: true
        users_enabled: true
        password_hashing:
            time: 1
            memory_kib: 65536
            parallelism: 4
            key_len: 64
            salt_len: 32

`time`¶

integer 1 LH_API_ADMIN_PASSWORD_HASHING_TIME

Number of iterations (time cost) for Argon2id. Higher values increase computation time.

`memory_kib`¶

integer 65536 LH_API_ADMIN_PASSWORD_HASHING_MEMORY_KIB

Memory usage in KiB for Argon2id. Default is 64 MiB.

`parallelism`¶

integer 4 LH_API_ADMIN_PASSWORD_HASHING_PARALLELISM

Number of parallel threads for Argon2id.

`key_len`¶

integer 64 LH_API_ADMIN_PASSWORD_HASHING_KEY_LEN

Length of the derived key in bytes.

`salt_len`¶

integer 32 LH_API_ADMIN_PASSWORD_HASHING_SALT_LEN

Length of the random salt in bytes.

`cors`¶

object / mapping optional

Configuration for CORS (Cross-Origin Resource Sharing) on the Admin API. CORS allows web browsers to make requests to the Admin API from different origins.

This is particularly useful for:

Using the Swagger UI documentation from a different server
Building admin dashboards hosted on different domains
Testing the Admin API from development tools

`tls`¶

object / mapping optional LH_API_ADMIN_TLS_

Configuration for TLS (Transport Layer Security) on the Admin API when running on a separate port. When enabled, the Admin API will serve HTTPS instead of HTTP.

config.yaml

api:
    admin:
        enabled: true
        port: 8443
        tls:
            enabled: true
            cert: /path/to/admin.crt
            key: /path/to/admin.key

`enabled`¶

boolean false optional LH_API_ADMIN_TLS_ENABLED

Enables or disables TLS for the Admin API. When enabled, the Admin API will serve HTTPS on the configured port.

`cert`¶

file path required when enabled LH_API_ADMIN_TLS_CERT

Path to the TLS certificate file for the Admin API.

`key`¶

file path required when enabled LH_API_ADMIN_TLS_KEY

Path to the TLS private key file for the Admin API.

config.yaml

api:
    admin:
        cors:
            enabled: true
            allow_origins: "*"
            allow_methods: "GET,POST,HEAD,PUT,DELETE,PATCH,OPTIONS"
            allow_headers: "Origin,Content-Type,Accept,Authorization"
            allow_credentials: true
            max_age: 3600

Quick Enable for Swagger UI

To quickly enable CORS for using Swagger UI from a different origin, you can simply set:

api:
    admin:
        cors:
            enabled: true

Or via environment variable:

export LH_API_ADMIN_CORS_ENABLED=true

The defaults are configured to work with Swagger UI out of the box.

Separate from Main Server CORS

The Admin API has its own CORS configuration, separate from the main server's server.cors settings. This allows different policies for federation endpoints vs. admin endpoints.

`enabled`¶

boolean false optional LH_API_ADMIN_CORS_ENABLED

Enables or disables CORS middleware for the Admin API.

`allow_origins`¶

string * optional LH_API_ADMIN_CORS_ALLOW_ORIGINS

Comma-separated list of allowed origins, or * to allow all origins.

Examples:

* - Allow all origins
https://admin.example.com - Allow only admin.example.com
https://admin.example.com,https://localhost:3000 - Allow multiple origins

`allow_methods`¶

string GET,POST,HEAD,PUT,DELETE,PATCH,OPTIONS optional LH_API_ADMIN_CORS_ALLOW_METHODS

Comma-separated list of allowed HTTP methods.

`allow_headers`¶

string Origin,Content-Type,Accept,Authorization optional LH_API_ADMIN_CORS_ALLOW_HEADERS

Comma-separated list of allowed request headers. The default includes Authorization to support HTTP Basic Authentication used by the Admin API.

`allow_credentials`¶

boolean true optional LH_API_ADMIN_CORS_ALLOW_CREDENTIALS

Indicates whether the request can include user credentials like cookies or HTTP authentication headers. Default is true to support HTTP Basic Authentication used by the Admin API.

Warning

When allow_credentials is true, allow_origins cannot be set to * in strict CORS implementations. However, Fiber's CORS middleware handles this by echoing back the requesting origin when credentials are allowed.

`expose_headers`¶

string empty optional LH_API_ADMIN_CORS_EXPOSE_HEADERS

Comma-separated list of headers that browsers are allowed to access.

`max_age`¶

integer 3600 optional LH_API_ADMIN_CORS_MAX_AGE

How long (in seconds) browsers should cache preflight request results. Default is 3600 (1 hour).

Complete Example¶

config.yaml (Admin API on separate port with TLS)

api:
    admin:
        enabled: true
        users_enabled: true
        port: 8443
        actor_source: header
        actor_header: X-Actor
        password_hashing:
            time: 1
            memory_kib: 65536
            parallelism: 4
            key_len: 64
            salt_len: 32
        cors:
            enabled: true
            allow_origins: "*"
            allow_methods: "GET,POST,HEAD,PUT,DELETE,PATCH,OPTIONS"
            allow_headers: "Origin,Content-Type,Accept,Authorization"
            allow_credentials: true
            max_age: 3600
        tls:
            enabled: true
            cert: /path/to/admin.crt
            key: /path/to/admin.key

config.yaml (Admin API on main server port)

api:
    admin:
        enabled: true
        users_enabled: true
        port: 0
        actor_source: header
        actor_header: X-Actor
        cors:
            enabled: false

When port: 0, the Admin API runs on the main server port and uses the main server's TLS configuration from server.tls.

Security Considerations¶

Production Deployments

In production, consider the following security measures for the Admin API:

Network isolation: Use a separate port and firewall rules to restrict access
TLS: Always use HTTPS for admin API traffic
Strong passwords: Use strong, unique passwords for admin users

Admin API Endpoints¶

The Admin API provides endpoints for managing:

Subordinates - Add, update, remove subordinate entities
Trust Mark Specs - Configure trust mark issuance specifications
Trust Marked Entities - Manage trust mark eligibility
Signing Configuration - Update signing algorithm and key rotation settings
Federation Metadata - Update entity metadata and authority hints
Users - Manage admin users (when users_enabled is true)

For detailed API documentation, see the OpenAPI specification at /admin/api/v1/docs when the Admin API is enabled.

Admin API

admin¶

enabled¶

users_enabled¶

port¶

actor_source¶

actor_header¶

password_hashing¶

time¶

memory_kib¶

parallelism¶

key_len¶

salt_len¶

cors¶

tls¶

enabled¶

cert¶

key¶

enabled¶

allow_origins¶

allow_methods¶

allow_headers¶

allow_credentials¶

expose_headers¶

max_age¶

Complete Example¶

Security Considerations¶

Admin API Endpoints¶

`admin`¶

`enabled`¶

`users_enabled`¶

`port`¶

`actor_source`¶

`actor_header`¶

`password_hashing`¶

`time`¶

`memory_kib`¶

`parallelism`¶

`key_len`¶

`salt_len`¶

`cors`¶

`tls`¶

`enabled`¶

`cert`¶

`key`¶

`enabled`¶

`allow_origins`¶

`allow_methods`¶

`allow_headers`¶

`allow_credentials`¶

`expose_headers`¶

`max_age`¶