Chronos/DBWaitlist

Gateway

Approvals

A held change put to a person: the console’s review queue, approval links, the widget in your product, single sign-on, and settling conflicts.

Self-hostedChronos Gateway runs on your own servers today. Releases and install script. The engine under it: Chronos DB, self-hosted

What a held change is

A run’s proposal that breaks a rule is held: nothing is written, and the run waits for a person. The person reads the change in plain words and approves it or rejects it. Approving writes the change to your database with the same row checks as any merge: each row is locked and compared first, in one transaction. Rejecting drops the run’s world.

  • A held change waits 3 days by default (GATEWAY_HOLD_TTL), then expires and its world is dropped.
  • While a run is held its agent cannot send SQL or MCP calls, and a second propose answers 409 held.
  • A person approves one version of the change: what they looked at. If the run’s world changed since, the approval is refused as stale.
  • A run in conflict is decided the same way: the person settles its conflicts and approves.
  • With the AI reviewer set up, a model decides held changes first, and a person sees only what it rejected or passed on. See Rules, labels and masks.

This page describes gateway 0.4.4 on Chronos DB 0.6.2.

Four ways to decide

WayWho decidesSigned in with
The console’s Review pageYour teamA developer key, or single sign-on
POST /v1/runs/:id/approve and /rejectYour backend or admin toolA developer key (cgk_...)
An approval link, or the widget in your productWhoever holds the link: your end user, or anyone you send it toThe link’s own token (cga_...)
The /approvals pageYour approversYour identity provider (OIDC)

The console’s Review queue

Open /console on the gateway’s address and go to Review. It lists held runs and runs in conflict, oldest first, and counts both. Each entry shows the run’s intent, its status, its tenant, when it started and the first reason it is waiting.

KeyDoes
jMoves to the next change in the queue.
kMoves to the one before.
aApproves and merges the change shown.
rTurns it down, after asking why.

The keys work on the Review page only, not while you type in a field or a question is open.

What is shown

  • The intent, the status, the tenant, who the run is for (end_user), when it started, when it is dropped if no one decides, and the run’s id. With several databases, which one.
  • Why it’s waiting: the reasons the rules gave.
  • AI reviewer: when a model looked first, whether it turned the change down or passed it on, its reason, the model’s name and how sure it was.
  • What it changes: the summary in words, then each change with its key. Opening a change shows the row before and after, changed columns first.
  • Up to 500 changes are shown, with a count of the rest.
  • For a conflict: each row changed on both sides as a table of columns, with the value as it was, the agent’s value, and the database’s value now. A column both sides changed is marked.

Deciding

  • Approve and merge writes the change now. The console sends the version you are looking at, so a change the agent altered since is refused and shown again.
  • Deletes are confirmed. When the part you approve deletes rows, the console asks first, with the count, and the button reads “Approve and delete”.
  • Only some tables. When a change touches more than one table, each has a tick box with its counts. Untick a table to merge the rest now and leave it waiting.
  • Turn down asks for a reason, kept with the run and sent in the webhook. Nothing reaches the database, and the agent’s copy is dropped.
  • What the agent read has changed. When the engine refuses the approval for that, the console says nothing was written and asks whether to approve anyway. See Reads changed since.
  • Send for approval makes an approval link for someone else. With single sign-on set up, it can name the one person who may decide. The link is shown once to copy, with when it stops working.

People on GATEWAY_OIDC_ADMINS use the whole console. People only on GATEWAY_OIDC_ALLOW can approve, on /approvals, not change settings. A key’s sign-in to the console ends when the key is revoked, or after 12 hours.

Approve and reject over the API

Both calls take a developer key.

POST /v1/runs/:id/approve
curl -s localhost:7400/v1/runs/$RUN/approve -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \  -d '{"by": "ada@example.com", "version": 12}'# {"status": "merged", "merged": 2}
FieldMeaning
versionThe version from GET /v1/runs/:id/changes. The merge happens only if the run’s world is still at it; otherwise 409 stale. Without it, whatever the world holds now is merged.
byWho decided, as your backend knows them. Kept in the run’s outcome and sent in merge.landed.
skip_read_checktrue: merge without checking what the run read. See Reads changed since.
only_tablesA list of table names: approve only those. See Approve a part.
only_keysA list of row keys, such as ["leads/7"]: approve only those rows.
by_columns, resolve, rows, targetHow to settle rows changed on both sides. See Conflicts.

Only a held run, or one in conflict, is approved. For any other run the answer is 409 with the run’s status as the code.

POST /v1/runs/:id/reject
curl -s localhost:7400/v1/runs/$RUN/reject -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \  -d '{"reason": "still a customer", "by": "ada@example.com"}'# {"status": "rejected"}

Rejecting takes reason and by. It drops the run’s world, sets the run to rejected and sends merge.rejected with both. Any run that is open, held, in conflict or failed can be rejected; one that is over answers 409 with its status.

Approve a part

Send only_tables or only_keys to merge a part of a held change. That part is written, and the rest stays in the run’s world. The run stays as it was, so you approve or reject the rest after.

approve the leads table only
curl -s localhost:7400/v1/runs/$RUN/approve -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \  -d '{"by": "ada@example.com", "only_tables": ["leads"]}'# {"status": "held", "merged": 2, "partial": true}
  • Each list must be non-empty and hold only names: 400 otherwise.
  • merge.landed is sent with partial: true.
  • A run approved in parts has several merge ids (merges). While the run is still held it is not undone: approve or reject the rest first. Once the rest is approved, the undo puts all of the parts back.
  • If the run instead ends rejected, expired or discarded, the part’s rows stay in the database. From 0.3.2 such a run can be undone for what that part wrote, with POST /v1/runs/:id/undo or the Undo button on its page in the console. See Undo.

Reads changed since

With the default rule check_reads = true, the engine checks at every merge that the rows the run read still match the database. A person’s approval is checked the same way. When they do not match, the approval answers 409 reads_changed and nothing is merged.

409 reads_changed
{"error": {"code": "reads_changed", "reasons": "...",  "message": "Nothing was merged: the run ... What it did may rest on rows as they were when it began. Look at its changes again; approve with skip_read_check: true to merge them without that check"}}

It means one of two things:

  • Rows the run read changed after it began: your app changed them in the database, or another run merged.
  • A table it read without a narrowing filter has more than 100,000 rows to check, which is too much to check.

Only the run’s own tenant’s rows count: another tenant’s rows changing do not hold it. Then choose:

  • Reject it and start a new run, so the agent works from the rows as they are now.
  • Approve anyway, with "skip_read_check": true, if the change still makes sense as it is. The merge runs without that check. The rows it changes are still locked and compared with the database. The run’s outcome and merge.landed say reads_checked: false.

Only a person can turn that check off, never an agent, and it cannot be turned back on for that run. The console and the approval widget both ask before they send it. Through an approval link, a reads_changed answer does not use the link up.

Conflicts

A run in conflict changed rows that the database, or main, changed too since its world was forked. Nothing was written. A person settles it by approving with how to settle the rows. The engine then judges the settled merge like any merge.

SendSettlesIn the console
"by_columns": trueEach side keeps the columns only it changed. Try this first.Combine by column
"by_columns": true, "resolve": "ours"As above; where both changed one column, the agent’s value.Combine by column; the agent’s value
"by_columns": true, "resolve": "theirs"As above; where both changed one column, the database’s value.Combine by column; the database’s value
"resolve": "ours"The agent’s whole rows, overwriting the other side’s changes to other columns.Overwrite with the agent’s whole rows
"resolve": "theirs"The database’s rows; the agent’s change to them is dropped.Keep the database’s rows
"rows": {"orders/7": ...}Single rows: "ours", "theirs", "delete", or the row to keep as an object.API only
"target": nRows settle against main as a preview of the merge saw it.API only
approve a run in conflict, combining by column
curl -s localhost:7400/v1/runs/$RUN/approve -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \  -d '{"by": "ada@example.com", "by_columns": true}'
  • If rows still conflict after that, the answer is 409 conflict again, with the rows in conflicts. Combining by column fails this way when both sides changed the same column: pick whose value wins.
  • An approval of a held run can find a conflict too: rows changed between the hold and the approval. The run then becomes conflict and merge.conflict is sent.
  • A person holding an approval link is told only that rows changed and nothing was written. The rows themselves, hidden columns included, go to a developer key or the console.
  • Beside MySQL, MariaDB and MongoDB the console shows a conflict’s rows to settle, as beside Postgres.

Strict changes

From 0.4.1, with engine 0.6.2. A held change that sends payment, payout, transfer or refund effects (NOTIFY ON MERGE on a channel starting with one of those), or ones its merge policy names in strict_channels, is strict: only a person approves it, and only within its window.

a strict hold
{"status": "held", "reasons": ["..."], "strict": {"channels": ["payout"], "until": 1795047300000}}
  • Where it shows: strict: {channels, until} (until in ms) is in the hold, in merge.held and in the propose’s answer. The window is the policy’s strict_window, 15 minutes by default, from the hold.
  • The AI reviewer never approves one. It passes it to a person with why.
  • A person’s approval after until is refused, 409 window_passed, through the API, an approval link or Chronos Cloud alike. Reject it, and have the agent propose again.
  • Other changes to the database since the hold supersede it (from 0.4.2). The hold records the state of the database it merges into (strict.target), and every approval merges bound to it: after other changes reached the database, 409 strict_target and nothing is merged. Reject it; the agent proposes again. A strict change is approved whole: only_tables or only_keys on one are refused (400).
  • The window holds through conflicts. Settling a strict run’s conflict is an approval like any, in the same window; proposed again into a conflict, it keeps its window; a new hold gives a new one.
  • When the gateway can’t tell, because the engine’s EXPLAIN MERGE failed at the hold, the change is taken as strict: strict has no channels and unchecked: true.
  • The widget shows the channels and the time left, and turns its Approve button off once it runs out. GET /v1/approve returns strict ({channels, until}, else null).

An approval link puts one held change to one person, once. Your backend asks for it with a developer key.

POST /v1/runs/:id/approvals
curl -s localhost:7400/v1/runs/$RUN/approvals -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \  -d '{"end_user": "user_7"}'
FieldMeaning
end_userWho the link is for, in your product’s terms. Kept with the decision. Default: the run’s end_user.
approverAn email. Single sign-on only: the link then works only for that person, signed in. 400 without single sign-on, or for an email the allow list could not allow.
expires_inSeconds the link works, from 1 to GATEWAY_APPROVAL_TTL. Default: GATEWAY_APPROVAL_TTL. Out of range: 400.
the answer
{  "token": "cga_...",  "run": "run_...",  "version": 12,  "end_user": "user_7",  "approver": null,  "expires": 1767312000000,  "link": "https://gateway.example.com/approve#cga_...",  "widget": {    "script": "https://gateway.example.com/widget.js",    "html": "<chronos-approve base=\"https://gateway.example.com\" token=\"cga_...\"></chronos-approve>"  }}
  • Once. A link decides one change one time. The gateway keeps only the token’s hash.
  • One version. Approving merges exactly the version the link was made at. If the run changed since, the page says so and the change can only be turned down; make a new link.
  • For a time. GATEWAY_APPROVAL_TTL is 1 day by default and is the most a link can last.
  • A bearer link. Whoever holds it decides, unless it names an approver or GATEWAY_OIDC_REQUIRE is on.
  • Only a held run. For a run that is not held the answer is 409 with the run’s status as the code. Propose it first.
  • A decision that was not carried out frees the link. If approving fails because the run changed since, what it read changed, or the engine was away, the link can be used again. After a conflict it stays used.

The hosted /approve page

link is a page of the gateway’s own, at /approve on GATEWAY_PUBLIC_URL, that shows the change with the widget. Send it to anyone: by email, in a chat, in a ticket. The token is after the #, so browsers never send it to a server and it is in no log. The page keeps it for the tab, so it is still there after a sign-in.

The widget

widget.script and widget.html put the same review inside your own product, so your end user approves where they already are.

in your page
<script src="https://gateway.example.com/widget.js"></script><chronos-approve base="https://gateway.example.com" token="cga_..."></chronos-approve>

It shows the run’s intent, the summary, each change in plain words such as “Remove lead “Hooli””, a note field, and Approve and Turn down buttons. Up to 200 changes are listed, with a count of the rest. In React, render the element as it is.

AttributeMeaning
baseThe gateway’s address, as the user’s browser reaches it (GATEWAY_PUBLIC_URL).
tokenThe approval token (cga_...). Changing either attribute loads the change again.
EventdetailWhen
chronos-decided{decision, result}A decision landed. decision is approve or reject (or undo, for an undo link). result is the gateway’s answer.
chronos-error{code, message}A call failed: the link is expired, used or invalid, the change is stale, and so on.

Both events bubble.

CSS variableSetsDefault
--chronos-accentThe colour of the main button and of focus rings.Lime, #c8ff2e
--chronos-on-accentThe text on the main button.Near black; white when the page set its own --chronos-accent
--chronos-radiusCorner radius.2px
--chronos-fontThe font.The system’s
listen and theme
<style>  chronos-approve { --chronos-accent: #1f6feb; --chronos-on-accent: #fff; --chronos-radius: 8px; }</style><script>  document.querySelector('chronos-approve').addEventListener('chronos-decided', (e) => {    console.log(e.detail.decision, e.detail.result);  });</script>
  • The widget follows the browser’s light or dark setting. Its card is exposed as the part card.
  • The user’s browser must reach the gateway at GATEWAY_PUBLIC_URL.
  • Your site’s origin must be in GATEWAY_ALLOWED_ORIGINS, comma-separated: https://app.example.com. Only the approval endpoints answer other sites’ pages; everything else is for servers.
  • When what the run read has changed, the widget says nothing was written and offers “Approve anyway” and “Turn down”.
  • An approval for a person signed in works on the gateway’s own pages only. On another site the widget cannot send the gateway’s cookie, so it says to sign in.

The widget’s calls

The widget makes two calls, with the approval token as the bearer token. You can make them yourself to build your own page.

CallBodyAnswers
GET /v1/approve{run: {id, intent, tenant, created}, end_user, approver, signed_in, expires, summary, changes, total, more, reasons, stale, strict}. stale is true when the run changed since the link was made. strict (from 0.4.1): {channels, until} for a strict change, else null.
POST /v1/approvedecision (approve or reject), reason, skip_read_checkThe run’s new status: {"status": "merged", "merged": n} or {"status": "rejected"}.
POST /v1/approve
curl -s https://gateway.example.com/v1/approve -H "Authorization: Bearer cga_..." -H 'Content-Type: application/json' \  -d '{"decision": "reject", "reason": "still a customer"}'

Single sign-on

Approval links are bearer links: whoever holds one decides. To know who decided, and to let only your approvers decide, connect the gateway to your OpenID Connect provider: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Auth0 and others.

  1. Make a client at your provider

    A web application: an OIDC client using the authorization-code flow, with the redirect URI GATEWAY_PUBLIC_URL + /sso/callback, for example https://gateway.example.com/sso/callback. Give it the openid, email and profile scopes, and a groups claim if you allow by group. Note its client ID and secret.

  2. Set these, then restart

    gateway.env
    GATEWAY_OIDC_ISSUER=https://acme.okta.comGATEWAY_OIDC_CLIENT_ID=0oa...GATEWAY_OIDC_CLIENT_SECRET=...GATEWAY_OIDC_ALLOW=@acme.com,group:db-approvers
  3. Send your approvers to /approvals

    They open https://gateway.example.com/approvals, sign in, see every held change, and approve or turn down each one after reading it in words.

SettingDefaultMeaning
GATEWAY_OIDC_ISSUERunsetYour provider’s issuer URL: https://acme.okta.com, https://login.microsoftonline.com/<tenant>/v2.0, https://accounts.google.com. It must be https://; plain http only to this machine.
GATEWAY_OIDC_CLIENT_IDunsetThe gateway’s client at your provider. Needed with the issuer.
GATEWAY_OIDC_CLIENT_SECRETunsetIts secret. Needed with the issuer. Sent with HTTP Basic (client_secret_basic).
GATEWAY_OIDC_ALLOWunset, requiredWho may approve: emails (ada@acme.com), whole domains (@acme.com) and groups (group:db-approvers), comma-separated. Anyone else your provider signs in is refused.
GATEWAY_OIDC_ADMINSunsetWho may sign in to the console and change settings, in the same form. They may also approve.
GATEWAY_OIDC_GROUPS_CLAIMgroupsThe ID token’s claim that lists a person’s groups (roles with Entra ID app roles).
GATEWAY_OIDC_REQUIREoffon: every approval link needs a person on the allow list, signed in. Off: only links made for an approver.
GATEWAY_OIDC_SESSION_TTL12hHow long a sign-in lasts.

With an issuer set, the client ID, the secret and the allow list are all needed: the gateway refuses the settings otherwise.

With single sign-on set up

  • POST /v1/runs/:id/approvals takes "approver": "ada@acme.com". That link works only for Ada, signed in. Anyone else who opens it is asked to sign in, and then refused.
  • With no group on your lists, an approver email the lists do not name is refused when the link is made. With a group on them, the gateway cannot know until that person signs in, and checks them then.
  • GATEWAY_OIDC_REQUIRE=on makes every approval link need someone on the allow list, signed in. Links for your end users, in the widget on your own site, then stop working: sign-ins are on the gateway’s own pages only.
  • A Slack message of a held change links to the change on /approvals, behind sign-in, in place of a link that approves by itself.

The sign-in

  • A sign-in is a cookie, chronos_gateway_session: HttpOnly, SameSite=Lax, and Secure when GATEWAY_PUBLIC_URL is https://. The gateway keeps only its hash.
  • The person is checked against the allow list on every request. Removing someone from GATEWAY_OIDC_ALLOW and restarting ends their access.
  • Signing out ends the sign-in at the gateway, not the person’s session at your provider. The next sign-in in that browser asks your provider who is there (prompt=login, or select_account on Google).
  • Someone refused sees why and can sign in with another account. The gateway’s log names the setting.
  • The gateway checks the ID token’s signature against your provider’s published keys, its issuer, audience, expiry and nonce, and uses PKCE.
  • It reads the provider’s settings the first time someone signs in, so it starts even while the provider is down.

Endpoints

These are a browser’s, with the sign-in cookie, on the gateway’s own pages.

CallAnswers
GET /sso/login302 to your provider’s sign-in. ?next=/approvals names a path of the gateway’s to come back to.
GET /sso/callbackYour provider’s answer. The ID token and the person are checked: 302 to next, signed in, or a page saying why not.
POST /sso/logout{ok}: the sign-in ended.
GET /approvalsThe page: the held changes, to review and decide signed in.
GET /v1/me{email, name, sub, groups}.
GET /v1/me/held{runs: [{id, intent, tenant, end_user, created, hold_expires, reasons}]}, newest first, 200 at most.
POST /v1/me/runs/:id/approvalAn approval of that held run for the person signed in, as POST /v1/runs/:id/approvals with approver. The /approvals page uses it to show the widget.

Who decided

Every approval records who made it. It is in the run’s outcome.approved_by, in the merge.landed event (by: "person", with approved_by), and on the run’s world in the engine. A rejection records the same as rejected_by, with the reason.

Decided throughapproved_by
The API, with a developer key{"by": <what your backend sent as by>, "via": "api"}
The console{"by": <email or name>, "person": {...}, "via": "console"}
An approval link or the widget{"end_user": "user_7", "via": "approval"}
Signed in with single sign-on{"end_user": ..., "person": {"email", "name", "sub", "groups"}, "via": "sso"}

From Slack

A webhook with format: "slack" posts each held change to a channel as a message: “Waiting for approval”, the intent, how many changes, and why it is held. The message carries a link to review and approve or reject it: an approval link made for it, good once, until GATEWAY_APPROVAL_TTL. With single sign-on the link goes to the change on /approvals instead, so nothing in the channel approves anything by itself. See Webhooks and Slack.

Error codes

Errors read {"error": {"message": "...", "code": "..."}}. These are the codes the approval calls give.

CodeStatusFromMeaning and what to do
stale409approve, the linkThe run’s changes changed since they were shown. Look at them again, then approve with the new version or make a new link.
reads_changed409approve, the linkWhat the run read changed since it began, or was too much to check. Nothing was merged. Reject it, or approve with skip_read_check. The error carries reasons.
conflict409approve, the linkRows the change touches changed in the database. Nothing was written. Settle it with a developer key or in the console.
window_passed409approve, the link, Chronos CloudFrom 0.4.1. A strict change whose window ran out. Nothing was merged. Reject it; the agent proposes again. The error carries strict.
strict_target409approve, the link, Chronos CloudFrom 0.4.2. A strict change approved after other changes reached the database since its hold. Nothing was merged. Reject it; the agent proposes again.
held, merged, rejected, expired, ...409approve, reject, approvals, the linkThe run is not in a state for this. The code is the run’s status: “only a held run is put to a person”, “this change is merged already”.
invalid401the linkThe approval token is not one the gateway knows.
used409the linkThe link was already used to decide. Make a new one if the change is still held.
expired410the linkThe link’s time ran out. Make a new one with POST /v1/runs/:id/approvals.
sign_in401the link, /v1/meThe change is for a person signed in. The error carries login, where to sign in.
not_yours403the linkThe change was put to another person than the one signed in.
not_allowed403sign-inThe person signed in at your provider, and neither GATEWAY_OIDC_ALLOW nor GATEWAY_OIDC_ADMINS names them.
no_sso404/sso/..., /v1/meSingle sign-on is not set up (GATEWAY_OIDC_ISSUER).
origin403/v1/me/runs/:id/approvalThe request came from another site’s page. Open the gateway’s pages at GATEWAY_PUBLIC_URL.
sso_provider502sign-inThe identity provider could not be reached or answered wrongly.
sso_token401sign-inThe ID token was refused: its signature, issuer, audience, expiry or nonce.
sso_person403sign-inThe ID token gives no email for the person, or the provider says the email is not verified. The email is the email claim, or else an email-shaped preferred_username or upn.
not_admin403the consoleSigned in by single sign-on, and not on GATEWAY_OIDC_ADMINS.

A 400 without a code means the body was wrong: a decision other than approve or reject, skip_read_check or by_columns that is not true or false, an approver that is not an email, or expires_in out of range. A 401 on /v1/approve without a code means no approval token was sent.

Next

Approvals · Chronos