Quick start

From nothing to a backend that signs users up, logs them in and protects its routes with authbase, on your own machine. Plan on well under half an hour. You need Docker with Compose v2, and one of Node 20.19+, JDK 21 or Go 1.27 for the example backend.

Concepts first? Concepts explains apps, API keys and tokens in two pages.

1. Start authbase

authbase cannot be downloaded yet: the source code and the container image are published with the first public release. Until then, these steps describe a run from a copy of the source.

cp deploy/.env.example deploy/.env
# the two required secrets, generated into deploy/.env (gitignored)
sed -i.bak "s|^AUTHBASE_MASTER_KEY=.*|AUTHBASE_MASTER_KEY=$(openssl rand -base64 32)|; s|^POSTGRES_PASSWORD=.*|POSTGRES_PASSWORD=$(openssl rand -hex 24)|" deploy/.env && rm deploy/.env.bak
docker compose -f deploy/compose.yaml up -d --build
curl -s localhost:8080/readyz     # {"checks":{"database":"ok","migrations":"ok"},"status":"ok"}

The first up builds the image from source (a few minutes). Keep a copy of AUTHBASE_MASTER_KEY somewhere safe: without it the signing keys in the database cannot be opened (Self-hosting: backups).

2. Create an app and an API key

Open http://localhost:8080 and:

1. Sign up with an email and a password of 12+ characters.
2. New app: a name, e.g. Cashmate; the slug (cashmate) is permanent and becomes part of your token issuer.
3. API keys → Create API key, named e.g. development. The key (sk_live_…) is shown once: copy it now.

Prefer the terminal? The same, with the CLI inside the container:

dc="docker compose -f deploy/compose.yaml exec authbase /authbase admin"
$dc create-account --email you@example.com          # prompts for a password
$dc create-app --owner you@example.com --slug cashmate --name Cashmate
$dc create-api-key --app cashmate --name development   # prints the key once

3. Put the key in your environment

The key is a server secret: environment only, never in code or a committed file. read -s keeps it out of your shell history:

export AUTHBASE_URL=http://localhost:8080
read -rs AUTHBASE_API_KEY && export AUTHBASE_API_KEY   # paste the key, then Enter

4. Run an example backend

Each one serves the same routes (Example backends). Pick yours:

# Node (Express): the SDK is used from source, so build it first
(cd sdk/typescript && npm ci && npm run build)
cd examples/express && npm install && npm start          # :3001

# Kotlin (Ktor)                                           # :3002
cd examples/ktor && ./gradlew run

# Kotlin (Spring Boot)                                    # :3003
cd examples/spring && ./gradlew bootRun

# Go, no SDK                                              # :3004
cd examples/go && go run .

5. Try it

APP=http://localhost:3001
curl -s -X POST $APP/signup -H 'Content-Type: application/json' \
  -d '{"email":"ada@example.com","password":"correct horse battery staple"}' | tee /tmp/ada.json
TOKEN=$(jq -r .access_token /tmp/ada.json)
curl -s $APP/me -H "Authorization: Bearer $TOKEN"       # {"id":"…","email":"ada@example.com","roles":[]}
curl -si $APP/admin -H "Authorization: Bearer $TOKEN" | head -1   # 403: Ada is not an admin

/me never calls authbase: the example verified the token against your app’s public keys, fetched once and cached. Ada now shows up in the dashboard under Users, where you can give her the admin role; her next login (or refresh) carries it.

examples/smoke.sh $APP runs the whole flow, refresh and logout included, and is what CI runs against every example.

6. Into your own backend

1. Install the SDK. Nothing is published yet, so from this checkout:
   • Node: cd sdk/typescript && npm ci && npm run build && npm pack, then npm install /path/to/authbase-node-0.1.0.tgz in your project (Node SDK).
   • Kotlin/JVM: cd sdk/kotlin && ./gradlew publishToMavenLocal, then mavenLocal() and io.github.burakmetehan.authbase:authbase-ktor:0.1.0 or …:authbase-spring-boot-starter:0.1.0 (Kotlin SDK).
   • Anything else: the API is plain JSON over HTTP and tokens are standard JWTs; the integration guide has Node, Go and Python code.
2. Sign-up, login, refresh and logout go from your backend to authbase with the API key. Pass the end-user’s IP as client_ip: rate limiting and the audit log use it.
3. Give your clients the tokens. Keep the refresh token out of JavaScript (an HttpOnly cookie, or your server’s session); the access token is short-lived (15 minutes by default).
4. Protect routes by verifying the access token locally (the SDK’s requireAuth / authenticate("authbase") / Spring’s resource server).
5. Before production, read Self-hosting: HTTPS, the reverse proxy, backups and the key runbooks.

Stop everything with docker compose -f deploy/compose.yaml down (add -v to delete the database too).