# 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`](openapi.yml)

## Installation

### Docker Deployment (Recommended)

A combined container with **both Authelia and Authelia-API** is available on Docker Hub as [`git24hcom/authelia-api`](https://hub.docker.com/r/git24hcom/authelia-api):

```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/authelia-api/raw/branch/main/install-authelia-api.sh | sudo bash
```

### Manual Installation

1. **Clone the repository**:
   ```bash
   git clone https://git.lohmar.co.uk/cclohmar/authelia-api.git
   cd 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, environment, and a full usage guide are provided under [`docs/postman/`](docs/postman/):

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

A bulk user creation example is at [`docs/examples/bulk-request.json`](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](https://git.lohmar.co.uk/cclohmar/authelia-api) and mirrored to [Codeberg](https://codeberg.org/cclohmar/authelia-api).

## License

MIT License