Passwordless authentication for your users using just an email address.
This repository contains the source code of the SimpleAuth.link API Service.
- Read the full documentation here.
- Try the API in the interactive Swagger UI.
- By leveraging the Ed25519 signature algorithm, the service deterministically generates a private key using your App ID and secret.
- This ensures that each token is cryptographically secure and uniquely tied to your application, eliminating the need to store sensitive keys.
- SimpleAuth.link works without a traditional database. It does not store any user data, including email addresses, on its servers.
- Instead, the data generated is self-contained, requiring no further information or state to be used. This stateless design increases security and reduces the risk of data breaches.
A token is composed of three parts — the expiration time, the signature and the user's email — base64url-encoded and separated by dots. Read more in the documentation.
- Go (the version declared in go.mod)
- Docker (optional, for containerized deployment)
git clone https://github.com/SimpleAuthLink/authapi.git
cd authapiapi/: Contains the core API endpoint definitions and routing logic, and the Go client inapi/client.cmd/: Entry points and command-line utilities for running the API server (authapi) and the demo (demo).docker/: Dockerfiles for containerized builds.notification/: Code handling user notifications.token/: Modules for token creation and management.scripts/: Helper scripts (e.g. swagger generation)..github/: GitHub-specific workflows and configurations (CI/CD, etc.).
go test ./...For development purposes, you can run the API server directly with Go. The entry point is cmd/authapi/main.go and it loads .env automatically when present:
go run ./cmd/authapiThe main flags (also configurable via environment variables):
--host(envHOST) — service host (default0.0.0.0)--port(envPORT) — service port (default8080)--secret(envSECRET) — secret used to generate the tokens--email-addr(envEMAIL_ADDR) — sender account address--email-user(envEMAIL_USER) — SMTP username--email-pass(envEMAIL_PASS) — SMTP password--email-host(envEMAIL_HOST) — SMTP server host--email-port(envEMAIL_PORT) — SMTP server port (default587)--queue-size(envNOTIFICATION_QUEUE_SIZE) — notification queue size (default1000)--queue-workers(envNOTIFICATION_QUEUE_WORKERS) — notification queue workers (default10)
-
Prepare the Environment File
Copy the
example.envfile to.envand edit the file to fill in your parameters:HOST="localhost" PORT=8080 EMAIL_ADDR="test@test.com" EMAIL_USER="test@test.com" EMAIL_PASS="smtp_server_password" EMAIL_HOST="smtp.example.com" EMAIL_PORT=587 SECRET="my_backend_secret" NOTIFICATION_QUEUE_SIZE=1000 NOTIFICATION_QUEUE_WORKERS=10
-
Build the Docker Image
docker build -f docker/Dockerfile.prod -t simpleauthlink . -
Run the Docker Container
docker run --name simpleauthlink --env-file .env -p ${PORT}:${PORT} simpleauthlink
The API listens on the
PORTvalue from your.env(default8080), both inside the container and on your host.
The api/client package provides a typed Go client for the API:
package main
import (
"log"
"github.com/simpleauthlink/authapi/api/client"
"github.com/simpleauthlink/authapi/token"
)
func main() {
cli, err := client.Default("<your-app-id>", "<your-app-secret>", false)
if err != nil {
log.Fatal(err)
}
// request a login token for a user
if err := cli.RequestToken(new(token.Email).SetString("user@example.com")); err != nil {
log.Fatal(err)
}
}