Documentation

Staso

Self-hosted authentication and session tokens.

Staso 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

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

# download and start
$ curl -sSL get.se.stanislav.net/install | sh
$ staso serve --data /var/lib/staso
→ listening on :3200 · api ready

By default Staso 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":"alice"}'
→ {"token":"eyJ..."}

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

#Configuration

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

# staso.yaml
data:    /var/lib/staso
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 staso binary is both the server and the client.

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