No description

Find a file

cclohmar 8cfd403c14 chore: reorganise docs/ folder for Postman, examples, and OpenAPI spec - Moved into docs/: docs/postman/collection.json ← authelia-api.postman_collection.json docs/postman/environment.json ← authelia-api.postman_environment.json docs/postman-guide.md ← POSTMAN_GUIDE.md docs/openapi.yml ← openapi.yml docs/examples/bulk-request.json ← example_bulk_request.json - Updated README.md with new paths and docs/ structure - Updated .dockerignore to reflect new layout - Removed stale pre-built binary from working tree		2026-07-15 18:03:52 +00:00
docker	Add Docker container combining Authelia + Authelia-API	2026-06-24 18:54:27 +00:00
docs	chore: reorganise docs/ folder for Postman, examples, and OpenAPI spec	2026-07-15 18:03:52 +00:00
src	feat: add policy management endpoints	2026-07-15 14:33:09 +00:00
.dockerignore	chore: reorganise docs/ folder for Postman, examples, and OpenAPI spec	2026-07-15 18:03:52 +00:00
.gitignore	chore: 3-stage Docker build from source, rename image to authelia-api	2026-07-15 16:55:28 +00:00
docker-compose.yml	chore: 3-stage Docker build from source, rename image to authelia-api	2026-07-15 16:55:28 +00:00
Dockerfile	chore: 3-stage Docker build from source, rename image to authelia-api	2026-07-15 16:55:28 +00:00
install-authelia-api.sh	chore: sync: ClausL-MacBook-Pro.local 2026-05-04 19:00	2026-05-04 19:00:55 +01:00
README.md	chore: reorganise docs/ folder for Postman, examples, and OpenAPI spec	2026-07-15 18:03:52 +00:00

README.md

Authelia API

A Go-based REST API and management layer that sits alongside an Authelia instance. Provides a "Source of Truth" in SQLite, handles bulk user onboarding via JSON, manages access control policies dynamically, 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
Policy Management: Full CRUD for access control policies with dry-run verification
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
OpenAPI 3.0 Spec: Complete API specification at openapi.yml

Installation

Docker Deployment (Recommended)

A combined container with both Authelia and Authelia-API is available on Docker Hub as git24hcom/authelia-api:

# 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.

Bare Metal (Quick Installation)

Runs the install script directly on the host alongside an existing Authelia installation:

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

Manual Installation

Clone the repository:

git clone https://git.lohmar.co.uk/cclohmar/authelia-api.git
cd authelia-api

Run the installer:
```
sudo ./install-authelia-api.sh
```

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

Get your bearer token:

Docker: The token is whatever you set as session.secret in your configuration.yml.

Bare metal: Read it from your existing Authelia configuration:

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

Then test the API:

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8080/api/health

API Testing with Postman

Postman collection, environment, and a full usage guide are provided under docs/postman/:

docs/postman/collection.json - Complete API collection with all 12 endpoints
docs/postman/environment.json - Environment variables (base URL, token)
docs/postman-guide.md - Setup, examples, and troubleshooting

A bulk user creation example is at docs/examples/bulk-request.json.

Files in This Repository

Dockerfile - 3-stage build: Authelia download → Go build → runtime image
docker-compose.yml - Quick Docker deployment with volumes
docker/ - Container entrypoint and configuration templates
src/ - Go source code (cmd/server, internal packages, migrations)
docs/ - Documentation, OpenAPI spec, Postman files, and usage examples
- docs/openapi.yml - OpenAPI 3.0.3 specification for all endpoints
- docs/postman-guide.md - Postman setup and usage guide
- docs/postman/ - Postman collection and environment files
- docs/examples/ - Example request payloads
install-authelia-api.sh - Bare-metal installation script

Mirror

This project is developed on git.lohmar.co.uk and mirrored to Codeberg.

License

MIT License