Herald - OTP and Verification Code Service

Herald v1.9.0 adds HERALD_CODE_HASH_KEY_PREVIOUS, a list of keys under which stored verification code digests are verified but not written, so HERALD_CODE_HASH_KEY can be changed without refusing outstanding challenges. It is empty by default and nothing changes unless it is set; challenge-kit moves to v1.14.0. Read the upgrade and rollback guidance before changing the key on more than one instance. For enabling the key introduced in v1.8.0, see upgrade from v1.7.0 to v1.8.0.
📧 Your Gateway to Secure Verification
🌐 Multi-language Documentation

Herald is a production-ready, standalone OTP and verification code service that sends verification codes via email and SMS. It features built-in rate limiting, security controls, and audit logging. Herald is designed to work independently and can be integrated with other services as needed.
The HTTP server uses Fiber v3. Dependency versions and the Go toolchain are pinned
in go.mod (Go 1.27.4 or later). Builds and validation run on Linux; use Linux
containers on macOS, Windows and other hosts.
Architecture

Core Features
- 🔒 Secure by Design: Challenge-based verification with Argon2 hash storage, HMAC or API-key request authentication with optional mTLS transport
- 📊 Built-in Rate Limiting: Multi-dimensional rate limiting (per user, per IP, per destination) with configurable thresholds
- 📝 Complete Audit Trail: Full audit logging for all operations with provider tracking
- 🔌 Pluggable Providers: Extensible email, SMS, and DingTalk provider architecture (email via herald-smtp, DingTalk via herald-dingtalk)
- ↩️ Challenge Revoke: POST /v1/otp/challenges/{id}/revoke to revoke (unbind/invalidate) a challenge when it is no longer needed
- 🔐 TOTP Proxy (Optional): When enabled, proxy TOTP (Authenticator) operations to herald-totp so one Herald URL covers OTP and TOTP
Current security upgrades
HMAC challenge creation requires v3. Use the v2 verification API with expected
user, purpose and channel from trusted application state. Upgrades from before
v1.3.10 require a coordinated activation index upgrade.
Keep Redis and audit volumes persistent. See provider diagnostics
for log field changes and historical log/trace handling. Other-language translations
are historical; current operational guides are maintained in English and Chinese.
For v1.3.13, follow the HMAC identity upgrade
before resuming creation traffic. Single-secret HMAC accepts only an omitted
key ID or default; legacy ambiguous records need reconciliation. Production
CORS lists must not contain standalone * entries. See the
changelog for this release.
Quick Start
Using Docker Compose
The easiest way to get started is with Docker Compose, which includes Redis:
# Required secrets: Compose refuses insecure repository-known defaults.
export REDIS_PASSWORD="$(openssl rand -hex 32)"
export HERALD_API_KEY="$(openssl rand -hex 32)"
# Needed to send email codes (see "Test the API"). Use an SMTP server that
# offers STARTTLS. Skip these to start Herald without a delivery provider.
export SMTP_HOST="smtp.example.com"
export SMTP_USER="herald@example.com"
export SMTP_PASSWORD="your-smtp-password"
export SMTP_FROM="herald@example.com"
# Start Herald and Redis in API-key mode
docker compose up -d
# Verify the service is running
curl http://localhost:8082/healthz
Expected response:
{
"status": "ok",
"service": "herald"
}
Test the API
Create a test challenge (requires authentication - see API Documentation).
Herald can only deliver a code on a channel that has a provider. The Compose
file registers the built-in SMTP provider for the email channel when the
SMTP_* variables above were set before docker compose up; replace
user@example.com with an address you can read.
# Reuse the key exported before docker compose up
export API_KEY="$HERALD_API_KEY"
# Create a challenge
curl -X POST http://localhost:8082/v1/otp/challenges \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"user_id": "test_user",
"channel": "email",
"destination": "user@example.com",
"purpose": "login"
}'
With a working SMTP provider the code is sent and the response is:
{
"challenge_id": "ch_...",
"expires_in": 300,
"next_resend_in": 60
}
Without a provider for the channel, or when the SMTP server rejects the
message, no code is sent and the response is an error with "ok": false and a
reason. The Compose stack uses the strict provider policy, so a failed
delivery is never reported as success. When the failure shows that no message
can have been accepted (the SMTP host does not resolve, nothing listens on the
port, the certificate is not trusted, the credentials are refused), the request
can be repeated at once. After any other failed send (a timeout, a dropped
connection, a command the server rejected) the resend cooldown (60 seconds by
default) stays in place and repeating the request answers
429/resend_cooldown. The Herald log line Failed to send verification code via provider carries a failure_category that says where the SMTP delivery
stopped (see troubleshooting). For SMS, DingTalk and the HTTP email
plugin see the Deployment Guide.
View Logs
# Docker Compose logs
docker compose logs -f herald
Manual Deployment
Builds and validation run on Linux. For macOS, Windows, and other environments, we recommend deploying Herald in a Linux container using Docker Compose.
For manual deployment and advanced configuration, see the Deployment Guide.
Basic Configuration
Herald requires minimal configuration to get started:
| Variable |
Description |
Default |
Required |
PORT |
Server port |
:8082 |
No |
REDIS_ADDR |
Redis address |
localhost:6379 |
No |
API_KEY |
API key for REQUEST_AUTH_MODE=api_key |
- |
Required in production API-key mode |
For email channel via herald-smtp, set HERALD_SMTP_API_URL (and optionally HERALD_SMTP_API_KEY); see Deployment Guide. For DingTalk channel, set HERALD_DINGTALK_API_URL (and optionally HERALD_DINGTALK_API_KEY); see Deployment Guide.
For complete configuration options including rate limits, challenge expiry, and provider settings, see the Deployment Guide.
Documentation
For Developers
- API Documentation - Complete API reference with authentication methods, endpoints, and error codes
- Deployment Guide - Configuration options, Docker deployment, and integration examples
For Operations
Documentation Index
For a complete overview of all documentation, see docs/enUS/README.md.
License
See LICENSE for details.