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

```bash
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**:
   ```bash
   # 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**:
   ```bash
   sudo ./install-authelia-api.sh
   ```

### Docker Deployment

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

```bash
# 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:

```bash
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](https://www.authelia.com/configuration/) for details on secrets, domains, authentication backends, and access control rules.

### Development Installation

For building from source, see the [src/README.md](src/README.md) file.

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

```bash
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):
   ```bash
   grep -A2 "session:" /opt/authelia/configuration.yml | grep "secret:" | awk '{print $2}'
   ```
3. **Test the API**:
   ```bash
   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](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](#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