Authelia API

A Go-based REST API and management layer that sits alongside an Authelia LXC on Proxmox. Provides a "Source of Truth" in SQLite, handles bulk user onboarding via JSON, and automates synchronization of the Authelia users_database.yml file.

Features

• Sovereign Bootstrap: Automatically imports existing Authelia users on first run
• Bulk User Management: Create multiple users via JSON API with automatic password generation
• Real-time Sync: SQLite changes automatically sync to Authelia's YAML configuration
• SMTP Onboarding: Send welcome emails using Authelia's SMTP configuration
• Secure API: Bearer token authentication with bcrypt hashing
• Drop-in Deployment: Runs alongside existing Authelia installation

Installation

Quick Installation (Recommended)

Download and execute the installation script:

curl -fsSL https://git.lohmar.co.uk/cclohmar/autehlia-api/raw/branch/main/install-authelia-api.sh | sudo bash

Manual Installation

1. Download the binary:

   # Download the latest authelia-api binary
   curl -fsSL -o authelia-api https://git.lohmar.co.uk/cclohmar/autehlia-api/raw/branch/main/authelia-api
   chmod +x authelia-api
   

2. Run the installer:

   sudo ./install-authelia-api.sh
   

Docker Deployment

A combined container with both Authelia and Authelia-API is available on Docker Hub:

# Create config directory with your Authelia configuration
mkdir -p config data certs
# Copy and edit the example config:
#   docker/configuration.yml.example → config/configuration.yml
#   Set secrets, domains, and other settings.

# Pull and start
docker compose up -d

Port	Service
9091	Authelia web portal
8080	Authelia-API (user management API)

First-time authentication: The container creates an admin user automatically on startup by reading the session.secret from your Authelia config. Whatever value you set for session.secret in configuration.yml becomes your initial bearer token — there is nothing to fetch. For example:

curl -H "Authorization: Bearer your-session-secret-value" http://localhost:8080/api/health

Authelia configuration reference: The example file at docker/configuration.yml.example covers the essentials, but Authelia has many more options. See the official Authelia configuration docs for details on secrets, domains, authentication backends, and access control rules.

Development Installation

For building from source, see the src/README.md file.

Note for local development: When installing from a cloned repository, set the environment variable to use the local binary:

AUTHELIA_API_DEVELOPMENT_MODE=true sudo ./install-authelia-api.sh

Quick Start

1. Install using the script above
2. Get your bearer token (from Authelia configuration):

   grep -A2 "session:" /opt/authelia/configuration.yml | grep "secret:" | awk '{print $2}'
   

3. Test the API:

   curl -H "Authorization: Bearer YOUR_TOKEN_HERE" http://127.0.0.1:8080/api/health
   

API Testing with Postman

Postman collection and environment files are provided for API testing:

• authelia-api.postman_collection.json - Complete API collection
• authelia-api.postman_environment.json - Environment variables
• POSTMAN_GUIDE.md - Setup and usage guide

See POSTMAN_GUIDE.md for detailed instructions.

Files in This Repository

• authelia-api - Ready-to-use binary (production)
• install-authelia-api.sh - Installation script
• Dockerfile - Combined Authelia + Authelia-API container image
• docker-compose.yml - Quick Docker deployment with volumes
• docker/ - Container entrypoint and configuration templates
• POSTMAN_GUIDE.md - API testing guide
• src/ - Source code and build instructions
• authelia-api.postman_collection.json - Postman collection
• authelia-api.postman_environment.json - Postman environment

Production Deployment

Docker (recommended): Use docker compose up -d — see Docker Deployment above.

Bare-metal: The repository also provides a ready-to-deploy binary. The installation script handles:

• Systemd service creation
• Database setup
• Configuration generation
• User creation
• Firewall configuration (if applicable)

License

MIT License