# Quick start

> Run authbase and an example backend on your machine, then move the integration into your own.

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](https://authbase.burakmetehan.com.tr/docs/concepts.md) 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.

```sh
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](https://authbase.burakmetehan.com.tr/docs/self-hosting.md#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:

```sh
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:

```sh
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](https://authbase.burakmetehan.com.tr/docs/examples.md)).
Pick yours:

```sh
# 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

```sh
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](https://authbase.burakmetehan.com.tr/docs/sdk/node.md)).
   - 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](https://authbase.burakmetehan.com.tr/docs/sdk/kotlin.md)).
   - Anything else: the API is plain JSON over HTTP and tokens are
     standard JWTs; the [integration guide](https://authbase.burakmetehan.com.tr/docs/integration.md) 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://authbase.burakmetehan.com.tr/docs/self-hosting.md): 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).