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

Authy

Authy is an open-source OTP (One-Time Password) service that generates, delivers, and verifies one-time passwords.

Prerequisites

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

System requirements

Authy requires:

  • Go 1.25.0 or higher - The Go programming language runtime and compiler
  • SQLite - Lightweight database (usually pre-installed on most systems)

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.25 \
  libsqlite3-dev \
  build-essential

For SQLCipher support (encrypted database):

sudo apt-get install -y libsqlcipher-dev

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

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

External services

Authy requires the Interface API service to be running:

Interface API

The Interface API service must be set up and running before starting Authy. The Interface API provides the core messaging infrastructure that Authy uses to deliver OTPs across different platforms.

See the Interface API setup guide for detailed installation instructions.

You will need:

  • Interface API URL (e.g., http://localhost:8082)
  • Interface API authentication token

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/Authy-API.git
cd Authy-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 DB_ENCRYPTION_KEY.

Alternatively, create the file manually:

cp example.env .env

Then edit .env and generate the required keys:

# Generate DB_ENCRYPTION_KEY (32 bytes hex, needed if encryption enabled)
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/authy.db
DISABLE_DB_ENCRYPTION=false
DB_ENCRYPTION_KEY=<generated-key>

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

# Interface API configuration
INTERFACE_API_URL=http://localhost:8082
INTERFACE_API_TOKEN=mt_xxxxx

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.

Verify the installation

Once running, verify everything is working:

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

# Access demo UI
open http://localhost:8080/demo

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

Important

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

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

Update the .env file with your Interface API connection details:

INTERFACE_API_URL=http://localhost:8082
INTERFACE_API_TOKEN=mt_xxxxx

Build the image

Build the Docker image:

docker build -t authy-api .

For encrypted database support with SQLCipher:

docker build --build-arg ENABLE_DB_ENCRYPTION=true -t authy-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 \
  authy-api \
  ./migrate -action=up

Run the container

Start the API server:

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

Stop the container

docker stop authy-api
docker rm authy-api

Docker Compose

Docker Compose provides a simple way to run Authy alongside its dependencies.

Note

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

Create docker-compose.yml

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

version: '3.8'

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

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

Start all services

docker compose up -d

This will start:

  • Database migrations
  • API server

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 Authy as a systemd service provides automatic startup, restart on failure, and integration with system logging.

Manual setup

1. Build the binary

make build

The make build command automatically detects the DISABLE_DB_ENCRYPTION setting in .env and uses the appropriate SQLite driver (SQLCipher or standard SQLite).

2. Create installation directory

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

3. Create dedicated user

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

4. Install systemd service

Create /etc/systemd/system/authy-api.service or copy from repository:

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

The service file should contain:

[Unit]
Description=ShortMesh Authy API
After=network.target

[Service]
Type=simple
User=shortmesh
Group=shortmesh
WorkingDirectory=/opt/authy-api
ExecStart=/opt/authy-api/bin/authy-api
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

5. Enable and start

sudo systemctl enable authy-api
sudo systemctl start authy-api

Managing the service

Once installed, manage the service with standard systemd commands:

# Start the service
sudo systemctl start authy-api

# Stop the service
sudo systemctl stop authy-api

# Restart the service
sudo systemctl restart authy-api

# View status
sudo systemctl status authy-api

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

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

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

# Disable auto-start
sudo systemctl disable authy-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 for external services in production
ALLOW_INSECURE_EXTERNAL=false

Database configuration

# Path to SQLite database file
SQLITE_DB_PATH=./data/authy.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 data. These are automatically generated by make setup.

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

Interface API configuration

Configuration for connecting to the Interface API service:

# Interface API service URL
INTERFACE_API_URL=http://localhost:8082

# Token for authenticating with Interface API
# Obtain from Interface API after creating a token
INTERFACE_API_TOKEN=mt_xxxxx

To obtain an Interface API token, see the Interface API documentation.

Database migrations

Authy 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/authy.db data/authy.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 authy-api

For more details, see the Migration Guide.

Using the API

Once Authy is running, you can interact with it using HTTP requests. See the API Usage Guide

API documentation

The Authy 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:

make docs

Demo UI

Authy includes a live demo UI that lets visitors test the complete OTP flow interactively.

Accessing the demo

The demo UI is available at:

http://localhost:8080/demo

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 /demo.

Security considerations

Key management

Never share or commit these sensitive values to version control:

  • DB_ENCRYPTION_KEY
  • INTERFACE_API_TOKEN

Never change the DB_ENCRYPTION_KEY after initial deployment as it will make the database unreadable.

Reverse proxy configuration

Example Nginx configuration with TLS:

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

    ssl_certificate /etc/letsencrypt/live/authy.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/authy.example.com/privkey.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