Interface API

The primary interface for user interaction.

Products

• Authy-API - Authentication API service

Table of Contents

• Requirements
• Quick Start
• Docker Setup
• API Usage
• Admin UI Management
• Configuration
• Development
• API Documentation
• Resources

Requirements

• Go 1.24.0+
• SQLite (SQLCipher optional, see Security)
• RabbitMQ (for worker service)
• Matrix Authentication Service (MAS) - See Matrix Client setup for configuration details
• Matrix Client - See Matrix Client repository for setup instructions

Ubuntu/Debian Dependencies

For SQLCipher support (encrypted database):

sudo apt-get update
sudo apt-get install -y libsqlite3-dev libsqlcipher-dev

Quick Start

git clone https://github.com/shortmesh/Interface-API.git
cd Interface-API
make setup
make migrate-up
make run

• Server: http://localhost:8080
• Swagger Docs: http://localhost:8080/docs/index.html
• Admin Dashboard: http://localhost:8080/admin

Docker Setup

Build and Run

# Build
docker build -t interface-api .

# Run
docker run -d --name interface-api -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/.env:/app/.env \
  interface-api

# View logs
docker logs -f interface-api

If AUTO_MIGRATE is disabled, run migrations first:

docker run --rm -v $(pwd)/data:/app/data -v $(pwd)/.env:/app/.env interface-api ./migrate -action=up

For database encryption, add build arg and configure .env:

docker build --build-arg ENABLE_DB_ENCRYPTION=true -t interface-api .

Set DISABLE_DB_ENCRYPTION=false and DB_ENCRYPTION_KEY in your .env.

Docker Compose

version: '3.8'

services:
  rabbitmq:
    image: rabbitmq:3-management-alpine
    ports:
      - "5672:5672"
      - "15672:15672"
    environment:
      RABBITMQ_DEFAULT_USER: guest
      RABBITMQ_DEFAULT_PASS: guest

  migrate:
    build: .
    command: ./migrate -action=up
    volumes:
      - ./data:/app/data
      - ./.env:/app/.env
    depends_on:
      - rabbitmq

  api:
    build: .
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
      - ./.env:/app/.env
    environment:
      - HOST=0.0.0.0
      - PORT=8080
      - RABBITMQ_URL=amqp://guest:guest@rabbitmq:5672/
    depends_on:
      - rabbitmq
      - migrate

docker-compose up -d

# View logs
docker-compose logs -f api

API Usage

For detailed information on using the API, see the API Usage Guide.

Admin UI Management

Access the web-based admin dashboard at http://localhost:8080/admin to manage Matrix tokens and devices through a graphical interface.

For detailed information on using the Admin UI, see the Admin UI Management Guide.

Configuration

Note

default.env contains operational default values. Only modify if you know what you're doing.

Copy example.env to .env and configure as needed:

cp example.env .env
# Or use: make setup (auto-generates keys)

Tip

Use make setup to automatically generate secure cryptographic keys

Server Configuration

• APP_MODE - Application mode: development or production
  • Production mode enforces HTTPS for server and external services (unless overridden)
  • Development mode has relaxed security settings
• HOST - Host address (default: 127.0.0.1)
• PORT - Port (default: 8080)

TLS/HTTPS Configuration (Production)

In production mode (APP_MODE=prod), the server requires HTTPS unless explicitly disabled:

• TLS_CERT_FILE - Path to TLS certificate file
• TLS_KEY_FILE - Path to TLS private key file

Security Overrides

Warning

Use these overrides with caution in production

• ALLOW_INSECURE_SERVER=true - Allow HTTP in production (use behind reverse proxy with TLS termination)
• ALLOW_INSECURE_EXTERNAL=true - Allow HTTP/WS for external services in production
• DISABLE_DB_ENCRYPTION=true - Disable SQLCipher encryption (use standard SQLite for development)

Required Environment Variables

The following environment variables must be set for the application to function properly:

Cryptographic Keys

Important

Auto-generated by make setup. Do not change after initial setup - will invalidate existing data.

• HASH_KEY - HMAC key for tokens (generate: openssl rand -base64 32)
• DB_ENCRYPTION_KEY - SQLCipher key (generate: openssl rand -hex 32, required if encryption enabled)

API Authentication

• CLIENT_ID - Client ID for API access (generate: openssl rand -hex 16)
• CLIENT_SECRET - Client secret for API access (generate: openssl rand -hex 32)

Matrix Services

Important

These services must be set up and running before starting the Interface API. See Matrix Client repository for setup instructions for both MAS and the Matrix Client.

• MAS_ADMIN_URL - MAS admin API URL
• ADMIN_CLIENT_ID - Admin client ID for MAS
• ADMIN_CLIENT_SECRET - Admin client secret for MAS
• MATRIX_CLIENT_URL - Matrix client URL

See example.env for all options.

Development

Commands

make setup             # Setup .env with auto-generated keys
make run               # Start API server
make worker            # Start message worker
make build             # Build binaries
make test              # Run tests
make docs              # Generate Swagger docs

Note

make run, make worker, and make build automatically detect the DISABLE_DB_ENCRYPTION setting in your .env and use the appropriate SQLite driver (SQLCipher or standard SQLite).

Migrations

make migrate-up       # Run pending
make migrate-down     # Rollback last
make migrate-status   # Show status

See Migration Guide for details.

API Documentation

• Swagger UI: http://localhost:8080/docs/index.html
• Regenerate: make docs

Resources

• API Usage Guide
• Admin UI Management
• Security & Environment Configuration
• Migration Guide
• Throttler Documentation
• QR Worker Documentation
• Architecture Documentation