# 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

### Docker Deployment (Recommended)

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.

### Bare Metal (Quick Installation)

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

```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
   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
   ```

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

**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:
  ```bash
  grep -A2 "session:" /opt/authelia/configuration.yml | grep "secret:" | awk '{print $2}'
  ```

Then test the API:
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost: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 with all endpoints
- `authelia-api.postman_environment.json` - Environment variables (base URL, token)
- `POSTMAN_GUIDE.md` - Setup and usage guide

See [POSTMAN_GUIDE.md](POSTMAN_GUIDE.md) for detailed setup and usage 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

## Mirror

This project is developed on [git.lohmar.co.uk](https://git.lohmar.co.uk/cclohmar/autehlia-api) and mirrored to [Codeberg](https://codeberg.org/cclohmar/autehlia-api).

## License

MIT License