Chappell AI

Builder's guide · Section 3

How the pieces fit

There are four parts, and only one of them talks to the books.

Browser your screens session cookie only no GAAPcore key Console server signs people in holds the writer key enforces your controls GAAPcore API knows applications authenticates the key idempotent writes PostgreSQL the books enforces the rules or refuses Console database people, sessions, approvals, audit trail kept apart: different database logins; neither can reach the other's data
Figure 1. The browser never holds an GAAPcore key. The console server calls GAAPcore as one registered application, called a writer.

The writer boundary

Every program that changes the books is a registered writer (in the database, a source_system). Your console is one writer. A bank-feed importer, an online-store connector or a nightly script would each be another. Every request a writer sends carries three things:

  1. Who it is: the X-Source-System header with the writer's code.
  2. Proof: Authorization: Bearer ak_…, the writer's API key.
  3. On every write, an Idempotency-Key, so a retried request never posts twice.

GAAPcore stamps the writer on every row the request creates. Your console adds the other half of the story: which person, signed in to the console, asked for it.

Why a server in the middle

The writer key can post to the books and does not expire on its own. If it reached a browser, anyone with that browser could post anything. The console server keeps the key, passes the browser's requests on to /v1/…, and adds the headers itself. It is also the one place every person's write passes through, which makes it the right place to enforce your approvals.