Quickstart

Quickstart

The goal here is a running server and your first authenticated API call in under ten minutes. This uses the local development stack, so you need Docker and Git installed.

1. Clone and start

git clone https://github.com/automoto/gg-scale.git
cd gg-scale
make up

make up starts three containers: the ggscale-server binary, Postgres, and Mailpit (an SMTP catcher with a web inbox at http://localhost:8025). The server listens on http://localhost:8080. The database migrates itself on startup, and any secrets the server needs are generated on first run.

2. Check health

curl -s localhost:8080/v1/healthz

You get back {"status":"ok"} and an X-API-Version: v1 response header. If the call hangs or the connection refuses, give the containers a few more seconds and check make logs.

3. Create the first admin

The control panel stays locked until you claim it with a one-time bootstrap token.

cat ./data/bootstrap.token

The same token prints in make logs at first startup. Open http://localhost:8080/v1/control-panel/setup, paste the token, and set an email and password for the first platform admin. Then sign in.

4. Make a tenant, project, and API key

Inside the control panel, create a tenant and a project. Creating them mints an API key. Copy it now, because it is hashed at rest and cannot be shown again. Your game sends this key on every player-facing call.

The dashboard labels the tenant "Account Tenant" and the project "Game Project". The API and this wiki call them tenant and project.

5. First authenticated call

Ask for an anonymous player session. Swap in the API key you just copied.

curl -s http://localhost:8080/v1/auth/anonymous \
  -X POST \
  -H "Authorization: Bearer <api_key>"

The response holds an access_token, a refresh_token, and a player_id:

{
  "access_token": "eyJ...",
  "refresh_token": "...",
  "player_id": 1,
  "external_id": "anon-...",
  "expires_at": "2026-08-01T00:00:00Z"
}

The access_token is the player session token. Send it as the X-Session-Token header on calls that act for that player. Here is a profile read:

curl -s http://localhost:8080/v1/profile \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Session-Token: <access_token>"

The API key says which game is calling, and the session token says which player it is calling for.

Where to go next

Read Core Concepts to understand the pieces you just used, or jump to the Feature Guides for a specific system.

Stopping and resetting

• make down stops the stack and keeps your data.
• make clean stops the stack and deletes its volumes, which resets the bootstrap token and every tenant.