toknd — Auth Broker

toknd is a minimal, centralized authentication and token broker. Built with Bun, Hono, and Redis, it serves as a middleware layer that manages OAuth2 providers, token persistence, and automatic refreshes, allowing your applications to focus on their core logic.

Features

• Centralized management for multiple OAuth2 providers (Google, Trakt, GitHub, etc.).
• Automatic token refreshes.
• Secure and isolated API access via API key authentication.
• Web-based dashboard for configuration management.
• Docker Compose support for simplified deployment.
• High performance and low-latency powered by Bun and Redis.

Tech Stack

• Runtime: Bun
• Web Framework: Hono
• Data Store: Redis
• Styling: Tailwind CSS & DaisyUI
• Schema & Validation: Zod

Getting Started

toknd can be deployed either as a containerized service or self-hosted directly on your hardware.

1. Environment Setup

Clone the repository and create your environment file:

cp .env.example .env

Define a strong API_KEY and ensure REDIS_URL points to a valid Redis instance.

2. Choose Deployment Method

Option A: Containerized (Recommended)

This is the easiest way to get up and running, as it bundles the application and a Redis instance together.

• Development (with Hot-Reload):

  podman compose up --build
  

• Production:

  docker compose up -d --build
  

Option B: Self-Hosting (Bare Metal)

Ideal for lightweight deployments or custom environments where you already have Bun and Redis.

1. Install Dependencies:

   bun install
   

2. Start the Server:
   • Development: bun run dev (with hot-reload)
   • Production: bun run start Note: Ensure your Redis server is running and accessible via the REDIS_URL in your .env.

---

API Reference

toknd provides a built-in Scalar API Reference that allows you to explore and test all endpoints directly from your browser.

• Interactive UI: http://localhost:3000/api (or /docs)
• OpenAPI Spec (JSON): http://localhost:3000/doc

All protected endpoints require a Bearer token in the Authorization header: Authorization: Bearer <your_master_api_key>

Core Concepts

• Token Brokerage: Automated access token retrieval and background refreshes for all configured providers.
• Provider Management: Register and manage OAuth2 providers via the Dashboard or the configuration API.

Dashboard

Access the toknd dashboard at: http://localhost:3000/app

The dashboard allows you to manage provider configurations, view live token statuses, and manually trigger refreshes. Authenticate using your Master API Key.

---