Running the Auth Service

The auth service (hone-auth) handles user authentication, device pairing, and subscription management. It runs as a native Perry binary on port 8445.

Configuration

Create auth.conf in the working directory with KEY=VALUE pairs:

DB_HOST=webserver.skelpo.net
DB_USER=hone
DB_PASS=<password>
DB_NAME=hone
PORT=8445
AUTH_SECRET=<shared-secret>
AUTH_BASE_URL=https://auth.hone.codes
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=<sendgrid-key>
SMTP_FROM=Hone <noreply@hone.dev>

Key	Required	Description
`DB_HOST`	Yes	MySQL server hostname
`DB_USER`	Yes	MySQL username
`DB_PASS`	Yes	MySQL password
`DB_NAME`	Yes	MySQL database name
`PORT`	No	Listen port (default: 8445)
`AUTH_SECRET`	Yes	Shared secret for JWT signing. Must match the relay service’s `auth.secret`.
`AUTH_BASE_URL`	Yes	Public URL for magic-link callbacks
`SMTP_HOST`	No	SMTP server for sending emails
`SMTP_PORT`	No	SMTP port (default: 587)
`SMTP_USER`	No	SMTP username
`SMTP_PASS`	No	SMTP password
`SMTP_FROM`	No	From address for emails

Database Setup

The auth service uses MySQL. Create the database and user:

CREATE DATABASE hone;
CREATE USER 'hone'@'%' IDENTIFIED BY '<password>';
GRANT ALL PRIVILEGES ON hone.* TO 'hone'@'%';

Tables are created automatically on first startup. The schema uses camelCase for all identifiers (table names, column names).

Running

cd /opt/hone-auth && ./hone-auth

The service reads auth.conf from its working directory.

Health Check

GET /health

Returns 200 OK when the service is running and the database connection is healthy.

Authentication Flow

Magic link request: Client sends email address to POST /auth/magic-link. The service generates a one-time token and emails a login link.
Token verification: User clicks the link, which hits GET /auth/verify?token=<token>. The service validates the token and returns a JWT.
Device pairing: Client registers a device with POST /auth/devices using the JWT. The service returns a device token used for relay authentication.

Development Mode

If SMTP configuration is omitted, magic-link tokens are logged to stdout instead of emailed. This enables local development without an email provider.

[dev] Magic link token for user@example.com: abc123def456

Shared Secret

The AUTH_SECRET value is critical for the system to work end-to-end:

The auth service uses it to sign JWTs and device tokens.
The relay service uses the same secret (as auth.secret in relay.conf) to validate device tokens locally, without making HTTP calls back to the auth service.

If these values do not match, devices will fail to authenticate with the relay.

Keyboard shortcuts

Hone Documentation