Authy API

The authentication service for OTP generation, delivery, and verification.

Table of Contents

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

Requirements

• Go 1.25.0+
• SQLite (SQLCipher optional, see Security)
• Interface-API - See Interface-API 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/Authy-API.git
cd Authy-API
make setup
make migrate-up
make run

Server: http://localhost:8080

Docker Setup

Important

The Interface API service must be set up and running before starting Authy-API. See Interface-API repository for setup instructions.

Build and Run

# Build
docker build -t authy-api .

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

# View logs
docker logs -f authy-api

If AUTO_MIGRATE is disabled, run migrations first:

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

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

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

Set DISABLE_DB_ENCRYPTION=false and DB_ENCRYPTION_KEY in your .env.

Docker Compose

Note

This configuration assumes Interface-API is running separately. Update INTERFACE_API_URL in your .env to point to the Interface-API service.

version: '3.8'

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

  api:
    build: .
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
      - ./.env:/app/.env
    environment:
      - HOST=0.0.0.0
      - PORT=8080
    depends_on:
      - migrate

docker-compose up -d

# View logs
docker-compose logs -f api

Configuration

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=production), 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 for external services in production
• DISABLE_DB_ENCRYPTION=true - Disable SQLCipher AES-256 encryption (not recommended, see Security)

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.

• DB_ENCRYPTION_KEY - SQLCipher key (generate: openssl rand -hex 32, required if encryption enabled)

Interface API

Important

The Interface API service must be set up and running before starting Authy-API. See Interface-API repository for setup instructions.

• INTERFACE_API_URL - Interface API service URL
• INTERFACE_API_TOKEN - Token for authenticating with Interface API

See example.env for all options.

Development

Commands

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

Note

make run and make build automatically detect the DISABLE_DB_ENCRYPTION setting in .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 Usage

See API Usage Guide for endpoint examples and integration.

Demo UI

A live demo UI is available at /demo to test the OTP flow interactively.

Building the Demo

The demo UI is a Vite-based React application located in pkg/web/. To build and serve it:

# Build the demo UI
cd pkg/web
make build

# Build the API server (embeds the UI)
cd ../..
make build

The demo UI is automatically embedded into the API binary and served at http://localhost:8080/demo.

Demo Features

• Phone number input with international format support
• Platform selection (WhatsApp, Signal, Telegram)
• OTP generation and delivery
• OTP verification

See pkg/web/README.md for detailed documentation on the demo UI.

API Documentation

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

Regenerate: make docs

Resources

• API Usage Guide
• Security & Environment Configuration
• Migration Guide