Retavon Retavon

Blog

We built the API first, and keys before people

Retavon's first commit was an API module. Keys with permissions came before people could sign in, and both came before the first screen. Why that order matters.

Michael Cooper,

A lot of business software is built screen first. The application is the screens; the API comes later, often as a separate project, exposing some of what the screens can do.

We built Retavon the other way round. In the order the commit log shows:

  1. The first commit: keeping each business's data apart, and the first API module.
  2. API keys bound to staff and roles, with permissions enforced on every call, then closing every way a key could see figures its roles should not.
  3. People signing in, through the API.
  4. The first screens of the web app: a counter running a day.

Why keys before people

An assistant signs in with a key. If the permission model is designed for keys first, a person signing in is simply someone holding a key through a browser session: the same roles, the same stores, the same refusals. In software designed for people first, an API key is often a single shared token, because the permission model was built around screens.

In Retavon a key is issued for a person, by that person, and acts as them. It can be read-only, it expires, and it can never hold a permission its issuer does not. A salesperson's Claude can do what the salesperson can, at the stores they work. Keys were the first identity the system had, so that was the shape permissions took from the start.

The web app is a client of the API

Retavon's web app has its own small server. It keeps the person's session in a sealed cookie, so their key never reaches the browser, and it passes every change through to the same /v1 API an assistant calls. Taking a deposit, closing a drawer, a manager approving a discount at the counter: each is an API call, checked by the same rules, written to the same audit trail.

When a screen needs something the API cannot do, the fix goes in the API, and every assistant gets it at the same time as the screen.

One work order, two ways in

Because records carry their own next steps, the screen and the API agree about what can happen. Work order 1099 is open. The service manager sees two buttons, Finish the job and Cancel the work order. An assistant asking the API for the same record gets completeWorkOrder and cancelWorkOrder in its next list, each with the reason it applies.

Work order 1099 in the Retavon web app: the customer reports weak jets and a humming pump on a 2012 spa, a visit is booked, and the page offers Finish the job and Cancel the work order.Work order 1099 in the Retavon web app: the customer reports weak jets and a humming pump on a 2012 spa, a visit is booked, and the page offers Finish the job and Cancel the work order.

What it cost

Building this way puts the screens last. Every screen waits for its operations to exist and be right. Some screens need several records at once in a shape no single operation returns, so the web app's server composes those reads for the screen. Those reads are for display only: every change still goes through the API.

Where we learned this

We had built this way before. AGLedger, change control for AI agents, is agent memory, approvals, delegations, an audit trail and notifications behind one API. Building it taught us that an agent's identity, what it may do, and the record of what it did have to be in the foundation. Retavon started there on its first day.