Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Interface API

The Interface API is the primary service for user interaction in the Shortmesh ecosystem. It provides a RESTful interface for managing authentication tokens, devices, messaging, and webhooks.

Prerequisites

Before installing the Interface API, you’ll need to ensure you have the required dependencies and external services.

System requirements

The Interface API requires:

  • Go 1.24.0 or higher - The Go programming language runtime and compiler
  • SQLite - Lightweight database (usually pre-installed on most systems)
  • RabbitMQ - Message broker for background workers

Optional but recommended:

  • SQLCipher - For encrypted database support

Installing dependencies

Debian/Ubuntu

Install the required system dependencies:

sudo apt-get update
sudo apt-get install -y \
  golang-1.24 \
  libsqlite3-dev \
  libsqlcipher-dev \
  build-essential

If your distribution doesn’t have Go 1.24 in the default repositories, download it from go.dev/dl:

wget https://go.dev/dl/go1.24.0.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.24.0.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

Install RabbitMQ:

External services

The Interface API requires two external Shortmesh services to be running:

Matrix Authentication Service (MAS)

MAS provides OAuth2/OIDC authentication for Matrix. You must configure and run MAS before starting the Interface API. See the Matrix Client MAS setup guide for detailed instructions.

Matrix Client

The Matrix Client service acts as a bridge between the Interface API and the Matrix homeserver. It handles device management, message sending, and webhook delivery. Refer to the Matrix Client documentation for setup instructions.

Quick setup

The quickest way to get started is to use the automated setup script. This method is ideal for development and testing.

Clone the repository

git clone https://github.com/shortmesh/Interface-API.git
cd Interface-API

Generate configuration

The setup script automatically creates a .env file with cryptographically secure keys:

make setup

This creates a .env file with auto-generated values for HASH_KEY, DB_ENCRYPTION_KEY, CLIENT_ID, and CLIENT_SECRET.

Alternatively, create the file manually:

cp example.env .env

Then edit .env and generate the required keys:

# Generate HASH_KEY (32 bytes base64)
openssl rand -base64 32

# Generate DB_ENCRYPTION_KEY (32 bytes hex, needed if encryption enabled)
openssl rand -hex 32

# Generate CLIENT_ID
openssl rand -hex 16

# Generate CLIENT_SECRET
openssl rand -hex 32

Configure environment variables

Edit your .env file with the required settings:

# Application mode: development or production
APP_MODE=development

# Server settings
HOST=127.0.0.1
PORT=8080

# Database configuration
SQLITE_DB_PATH=./data/shortmesh.db
DISABLE_DB_ENCRYPTION=false
DB_ENCRYPTION_KEY=<generated-key>

# Auto-run migrations (disable in production)
AUTO_MIGRATE=true

# External services (update with your values)
MAS_URL=https://mas.example.com
MAS_ADMIN_URL=https://mas.example.com/admin
ADMIN_CLIENT_ID=your-mas-admin-client-id
ADMIN_CLIENT_SECRET=your-mas-admin-client-secret
MATRIX_CLIENT_URL=http://localhost:3000

# RabbitMQ
RABBITMQ_URL=amqp://guest:guest@localhost:5672/

For a complete reference of all configuration options, see Configuration reference.

Initialize the database

Run migrations to set up the database schema:

make migrate-up

Check the migration status:

make migrate-status

Start the server

make run

The server will start and listen on http://localhost:8080. The API server includes embedded background workers for message processing.

Verify the installation

Once running, verify everything is working:

# View Swagger documentation in browser
open http://localhost:8080/docs/index.html

# Access admin dashboard
open http://localhost:8080/admin

The server provides:

Docker

Docker provides an isolated environment and simplifies dependency management. This is suitable for both development and production deployments.

Prerequisites

Ensure you have Docker installed:

# Verify Docker installation
docker --version

Create configuration

Before building the Docker image, you need a .env file. You can create it locally:

cp example.env .env
# Edit .env with your configuration

Or use the setup script:

make setup

Build the image

Build the Docker image:

docker build -t interface-api .

For encrypted database support with SQLCipher:

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

Then ensure your .env has:

DISABLE_DB_ENCRYPTION=false
DB_ENCRYPTION_KEY=<your-64-char-hex-key>

Run migrations

If you’ve disabled automatic migrations (AUTO_MIGRATE=false), run them manually:

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

Run the container

Start the API server:

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

Stop the container

docker stop interface-api
docker rm interface-api

Docker Compose

Docker Compose orchestrates all required services including RabbitMQ, and migrations. This is the recommended approach for production deployments.

Create docker-compose.yml

Create a docker-compose.yml file in your project directory:

version: '3.8'

services:
  rabbitmq:
    image: rabbitmq:3-management-alpine
    container_name: shortmesh-rabbitmq
    ports:
      - "5672:5672"
      - "15672:15672"
    environment:
      RABBITMQ_DEFAULT_USER: guest
      RABBITMQ_DEFAULT_PASS: guest
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq
    restart: unless-stopped

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

  api:
    build: .
    container_name: shortmesh-api
    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
    restart: unless-stopped

volumes:
  rabbitmq_data:

Start all services

docker compose up -d

This will start:

  • RabbitMQ message broker with management UI
  • Database migrations
  • API server (with embedded background workers)

View logs

# All services
docker compose logs -f

# API server logs
docker compose logs -f api

Access services

Stop services

# Stop all services
docker compose down

# Stop and remove volumes
docker compose down -v

Rebuild after changes

docker compose up -d --build

Systemd service

For production Linux deployments, running the Interface API as a systemd service provides automatic startup, restart on failure, and integration with system logging.

Automated setup

The repository includes a setup script that handles the installation:

sudo make setup-systemd

This script will:

  1. Create the /opt/interface-api directory
  2. Build the binaries
  3. Copy files to the installation directory
  4. Install the systemd service unit

Manual setup

If you prefer manual setup or need more control, follow these steps:

1. Build the binaries

make build

2. Create installation directory

sudo mkdir -p /opt/interface-api
sudo cp -r bin migrations default.env .env /opt/interface-api/
sudo mkdir -p /opt/interface-api/data

3. Create dedicated user

sudo useradd --system --user-group shortmesh
sudo chown -R shortmesh:shortmesh /opt/interface-api

4. Install systemd service

sudo cp interface-api.service /etc/systemd/system/
sudo systemctl daemon-reload

5. Enable and start

sudo systemctl enable interface-api
sudo systemctl start interface-api

Managing the service

Once installed, manage the service with standard systemd commands:

# Start the service
sudo systemctl start interface-api

# Stop the service
sudo systemctl stop interface-api

# Restart the service
sudo systemctl restart interface-api

# View status
sudo systemctl status interface-api

# View logs
sudo journalctl -u interface-api -f

# View logs since last boot
sudo journalctl -u interface-api -b

# Enable auto-start on boot
sudo systemctl enable interface-api

# Disable auto-start
sudo systemctl disable interface-api

Configuration reference

This section provides a complete reference for all configuration options available in the .env file.

Server configuration

# Application mode: development or production
# Production mode enforces HTTPS and stricter security
APP_MODE=development

# Host address to bind to
# Use 127.0.0.1 for localhost only, 0.0.0.0 for all interfaces
HOST=127.0.0.1

# Port to listen on
PORT=8080

# Logging level: debug, info, warn, error
LOG_LEVEL=info

TLS/HTTPS configuration

When running in production mode (APP_MODE=production), HTTPS is enforced. Configure TLS certificates:

# Path to TLS certificate file (PEM format)
TLS_CERT_FILE=/path/to/cert.pem

# Path to TLS private key file (PEM format)
TLS_KEY_FILE=/path/to/key.pem

To generate self-signed certificates for testing:

openssl req -x509 -newkey rsa:4096 \
  -keyout key.pem -out cert.pem \
  -days 365 -nodes

Security overrides

These options allow you to relax security constraints. Use with caution in production:

# Allow HTTP in production (for use behind a reverse proxy with TLS termination)
ALLOW_INSECURE_SERVER=false

# Allow HTTP/WebSocket for external services in production
ALLOW_INSECURE_EXTERNAL=false

Database configuration

# Path to SQLite database file
SQLITE_DB_PATH=./data/shortmesh.db

# Database encryption with SQLCipher
# Set to false to enable encryption (requires SQLCipher)
DISABLE_DB_ENCRYPTION=true

# Encryption key (64-character hexadecimal string)
# Required when DISABLE_DB_ENCRYPTION=false
# Generate with: openssl rand -hex 32
DB_ENCRYPTION_KEY=

# Automatically run migrations on startup
# IMPORTANT: Set to false in production and run migrations manually
AUTO_MIGRATE=true

Cryptographic keys

Warning

Never change these keys after initial setup. Changing them will invalidate all existing tokens and encrypted data. These are automatically generated by make setup.

# HMAC key for signing tokens (base64 encoded, 32 bytes)
# Generate with: openssl rand -base64 32
HASH_KEY=

# Database encryption key (hexadecimal, 32 bytes)
# Generate with: openssl rand -hex 32
DB_ENCRYPTION_KEY=

API authentication

Credentials for clients to authenticate with the API:

# Client ID (hexadecimal string)
# Generate with: openssl rand -hex 16
CLIENT_ID=

# Client secret (hexadecimal string)
# Generate with: openssl rand -hex 32
CLIENT_SECRET=

External services

Configuration for Matrix services:

# Matrix Authentication Service public URL
MAS_URL=https://mas.example.com

# Matrix Authentication Service admin API URL
MAS_ADMIN_URL=https://mas.example.com/admin

# Admin credentials for MAS
ADMIN_CLIENT_ID=your-mas-admin-client-id
ADMIN_CLIENT_SECRET=your-mas-admin-client-secret

# Matrix Client service URL
MATRIX_CLIENT_URL=http://localhost:3000

RabbitMQ configuration

# RabbitMQ connection URL
RABBITMQ_URL=amqp://guest:guest@localhost:5672/

For production, use authenticated connections:

RABBITMQ_URL=amqp://username:password@rabbitmq-host:5672/

Worker configuration

The default.env file contains worker and queue settings. These typically don’t need modification:

# Enable/disable message workers
WORKER_ENABLED=true
WORKER_COUNT=2

# Enable/disable webhook workers
WEBHOOK_WORKER_ENABLED=true
WEBHOOK_REFRESH_INTERVAL_SECONDS=30

# Enable/disable cleanup worker
CLEANUP_ENABLED=true
MATRIX_TOKEN_CLEANUP_INTERVAL_MINUTES=60

Database migrations

The Interface API uses migrations to manage database schema changes. Migrations ensure your database structure is up to date with the codebase.

Running migrations

For development with automatic migrations enabled (AUTO_MIGRATE=true), migrations run automatically when the server starts. For production or manual control, use these commands:

# Apply all pending migrations
make migrate-up

# Check migration status
make migrate-status

# Rollback the last migration
make migrate-down

Manual migration commands

You can also run the migration tool directly:

# Apply all pending migrations
go run cmd/migrate/main.go -action=up

# Rollback last migration
go run cmd/migrate/main.go -action=down -steps=1

# Show migration status
go run cmd/migrate/main.go -action=status

Production migration workflow

For production environments:

  1. Always set AUTO_MIGRATE=false in your .env file
  2. Back up your database before running migrations
  3. Run migrations during scheduled maintenance windows
  4. Test migrations on a staging environment first
  5. Verify migration success before restarting services

Example workflow:

# 1. Backup the database
cp data/shortmesh.db data/shortmesh.db.$(date +%Y%m%d_%H%M%S).backup

# 2. Check what migrations will be applied
make migrate-status

# 3. Run migrations
make migrate-up

# 4. Verify success
make migrate-status

# 5. If successful, restart the API server
sudo systemctl restart interface-api

For more details, see the Migration Guide.

Using the API

Once the Interface API is running, you can interact with it using HTTP requests. The API uses two authentication methods depending on the operation.

Authentication methods

Basic Authentication is used for managing credentials and tokens:

curl -u CLIENT_ID:CLIENT_SECRET http://localhost:8080/api/v1/tokens

Bearer Authentication is used for device and message operations:

curl -H "Authorization: Bearer mt_xxxxx" http://localhost:8080/api/v1/devices

Creating your first token

The first token you create is automatically marked as an admin token and creates the host Matrix identity:

# Extract credentials from .env
CLIENT_ID=$(grep '^CLIENT_ID=' .env | cut -d'=' -f2)
CLIENT_SECRET=$(grep '^CLIENT_SECRET=' .env | cut -d'=' -f2)

# Create admin token
curl -X POST http://localhost:8080/api/v1/tokens \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"use_host": false}'

Response:

{
  "message": "Matrix token created successfully",
  "token": "mt_abc123..."
}

Save the token value for subsequent requests.

Managing devices

List available devices:

curl http://localhost:8080/api/v1/devices \
  -H "Authorization: Bearer mt_xxxxx"

API documentation

The Interface API provides interactive API documentation through Swagger UI. Access it at:

http://localhost:8080/docs/index.html

The Swagger UI allows you to:

  • Browse all available endpoints
  • View request and response schemas
  • Test API calls directly from your browser
  • See example payloads

To regenerate the Swagger documentation after code changes:

# Install swag tool (first time only)
go install github.com/swaggo/swag/cmd/swag@latest

# Generate docs
make docs

For detailed API usage examples and workflows, see the API Usage Guide.

Admin dashboard

The Interface API includes a web-based admin dashboard for managing tokens and devices through a graphical interface.

Access the dashboard at:

http://localhost:8080/admin

Features include:

  • Token management (create, view, delete)
  • Device monitoring and status
  • Permission management

For detailed admin UI documentation, see the Admin UI Guide.

Troubleshooting

Debug logging

Enable debug logging for troubleshooting:

# Set in .env
LOG_LEVEL=debug

# Or run with debug logging
LOG_LEVEL=debug make run

Security considerations

Key management

Never share or commit these sensitive values to version control:

  • HASH_KEY
  • DB_ENCRYPTION_KEY
  • CLIENT_SECRET
  • ADMIN_CLIENT_SECRET

Never change these keys after initial deployment:

  • HASH_KEY - Will invalidate all existing tokens
  • DB_ENCRYPTION_KEY - Will make the database unreadable

Reverse proxy configuration

Example Nginx configuration with TLS:

server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

For more security guidance, see the Security Documentation.

Additional resources