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

Quick Start

1. Environment Setup

Clone the repository and create your environment file:

cp .env.example .env

Ensure you define a strong API_KEY in your .env.

2. Local Development (with Auto-Watch)

We use a Docker Compose override system to enable hot-reloading locally:

podman compose up --build

Note: This mounts your ./src directory into the container and uses bun --hot to restart on any code changes.

3. Production Deployment

For production, only the core docker-compose.yml is used:

docker compose up -d --build

API Reference

All protected endpoints require an Authorization header: Authorization: Bearer <your_master_api_key>

Token Brokerage

Get Valid Token: GET /api/token/:provider
- Returns a valid access token. Automatically triggers a refresh if the current one is expired.
Registry Status: GET /api/status
- Returns the connectivity and refresh status of all configured providers.

Authentication Flow

Initiate: GET /auth/:provider/login
Callback: GET /auth/callback (Handled internally by toknd)

Dashboard

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

Authenticate the registry using your Master API Key to manage your providers and view live token status.