Quickstart

You’ll run Plat5 and a starter API on your laptop, sign in, create an organization, and call the API as that organization. Then you’ll read the audit log Plat5 wrote along the way.

You need Docker, curl and jq, plus the toolchain for the starter you pick: Go 1.25+, Node 22+ with pnpm, or Bun.

1. Install the CLI.

   go install github.com/plat5dev/cli/cmd/plat5@latest
   plat5 version

   No Go? Download a binary from GitHub Releases and put plat5 on your PATH.

2. Create a project from a starter. --auth adds Plat5 Auth, a local sign-in provider, so you can get a token in the next steps.

   Go

   mkdir my-app && cd my-app
   plat5 init --template go-fiber-api --auth -y
   go mod tidy

   Node

   mkdir my-app && cd my-app
   plat5 init --template node-fastify-api --auth -y
   pnpm install

   Bun

   mkdir my-app && cd my-app
   plat5 init --template bun-effect-api --auth -y
   bun install

3. Start Plat5. This runs the gateway on :5001, Plat5 Auth on :5000, and publishes the starter’s routes.

   plat5 start
   plat5 status

4. Run your API in another terminal. It listens on :3000. You won’t call it directly: everything goes through the gateway.

   Go

   go run .

   Node

   pnpm run dev

   Bun

   bun run dev

5. Sign in. Locally, Plat5 Auth hands out a token for any email.

   TOKEN=$(curl -s -X POST http://localhost:5000/dev/token \
     -H 'Content-Type: application/json' \
     -d '{"email":"[email protected]"}' | jq -r .access_token)

6. Create an organization. You’re its first member, with the starter’s top role.

   ORG=$(curl -s -X POST http://localhost:5001/user/organizations \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"name":"Northwind"}' | jq -r .id)

7. Open a session in it. A session is a one-hour credential for one organization. It’s what a web app uses after the user picks an organization.

   SESSION=$(curl -s -X POST http://localhost:5001/user/organizations/$ORG/session \
     -H "Authorization: Bearer $TOKEN" | jq -r .token)

8. Call your API as the organization. The request says /org/projects. Your API receives /organizations/<your org id>/projects: Plat5 filled in the organization from the session.

   curl -s -X POST http://localhost:5001/org/projects \
     -H "X-API-Key: $SESSION" \
     -H 'Content-Type: application/json' \
     -d '{"name":"Launch"}' | jq
   
   curl -s http://localhost:5001/org/projects -H "X-API-Key: $SESSION" | jq

9. Read the audit log. The organization and the project you just created are both in it. Your API didn’t write a line of audit code.

   curl -s http://localhost:5001/org/audit-events -H "X-API-Key: $SESSION" | jq

What just happened

• Your API never saw a token. Plat5 checked the session, checked the route’s permission, applied the rate limit, recorded the request in the audit log, and put the organization id in the path.
• Calling /org/projects with the user token instead of the session is a 401: organization routes take an organization’s credential.
• The starter’s routes.yml says which routes exist and which permission each needs. Its roles.yml says which roles grant them.

Next

• plat5 start --observability adds Grafana with logs, traces, metrics and dashboards at localhost:3002.
• plat5 stop stops everything. Your data is kept for next time.
• Write a service to add your own routes.
• Routes and scopes explains the model behind the path rewrite.