Authentication Quick Start

5-minute guide to get started with MDDB authentication.

Start with Auth Enabled

cd services/mddbd

MDDB_AUTH_ENABLED=true \
MDDB_AUTH_JWT_SECRET=$(openssl rand -hex 32) \
MDDB_AUTH_ADMIN_USERNAME=admin \
MDDB_AUTH_ADMIN_PASSWORD=changeme \
go run .

Login

curl http://localhost:11023/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"changeme"}'

Save the token from the response.

Use Token

TOKEN="your-token-here"

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:11023/v1/stats

curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:11023/v1/add \
  -d '{
    "collection": "docs",
    "key": "welcome",
    "lang": "en",
    "contentMd": "# Welcome to MDDB"
  }'

Create API Key

curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:11023/v1/auth/api-key \
  -d '{"description":"My API key"}'

Save the API key (shown only once!).

Use API Key

curl -H "X-API-Key: mddb_live_..." \
  http://localhost:11023/v1/stats

Create User with Limited Access

curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:11023/v1/auth/register \
  -d '{"username":"alice","password":"secret123"}'

curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:11023/v1/auth/permissions \
  -d '{
    "username": "alice",
    "collection": "blog",
    "read": true,
    "write": false,
    "admin": false
  }'

Test Suite

Run automated tests:

./test-auth.sh    # Core authentication and RBAC
./test-mcp.sh     # MCP service integration
./test-panel.sh   # Panel UI (manual browser test)

Full Documentation

See AUTHENTICATION.md for complete documentation.

Need Help?

• Authentication not working? Check MDDB_AUTH_JWT_SECRET is set
• Getting 401? Make sure you include Authorization: Bearer TOKEN header
• Getting 403? User needs permissions - check with /v1/auth/permissions
• API key not working? Use X-API-Key header (not Authorization)

Disable Authentication

Set MDDB_AUTH_ENABLED=false or omit it (disabled by default).