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
| Way | Who decides | Signed in with |
|---|---|---|
| The console’s Review page | Your team | A developer key, or single sign-on |
POST /v1/runs/:id/approve and /reject | Your backend or admin tool | A developer key (cgk_...) |
| An approval link, or the widget in your product | Whoever holds the link: your end user, or anyone you send it to | The link’s own token (cga_...) |
The /approvals page | Your approvers | Your 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.
| Key | Does |
|---|---|
| j | Moves to the next change in the queue. |
| k | Moves to the one before. |
| a | Approves and merges the change shown. |
| r | Turns 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
versionyou 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.
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}| Field | Meaning |
|---|---|
| version | The 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. |
| by | Who decided, as your backend knows them. Kept in the run’s outcome and sent in merge.landed. |
| skip_read_check | true: merge without checking what the run read. See Reads changed since. |
| only_tables | A list of table names: approve only those. See Approve a part. |
| only_keys | A list of row keys, such as ["leads/7"]: approve only those rows. |
| by_columns, resolve, rows, target | How 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.
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.
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.landedis sent withpartial: 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,expiredordiscarded, the part’s rows stay in the database. From 0.3.2 such a run can be undone for what that part wrote, withPOST /v1/runs/:id/undoor 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.
{"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 andmerge.landedsayreads_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.
| Send | Settles | In the console |
|---|---|---|
| "by_columns": true | Each 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": n | Rows settle against main as a preview of the merge saw it. | API only |
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
conflictagain, with the rows inconflicts. 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
conflictandmerge.conflictis 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.
{"status": "held", "reasons": ["..."], "strict": {"channels": ["payout"], "until": 1795047300000}}- Where it shows:
strict: {channels, until}(untilin ms) is in the hold, inmerge.heldand in the propose’s answer. The window is the policy’sstrict_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
untilis refused, 409window_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, 409strict_targetand nothing is merged. Reject it; the agent proposes again. A strict change is approved whole:only_tablesoronly_keyson 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 MERGEfailed at the hold, the change is taken as strict:stricthas no channels andunchecked: true. - The widget shows the channels and the time left, and turns its Approve button off once it runs out.
GET /v1/approvereturnsstrict({channels, until}, else null).
Approval links
An approval link puts one held change to one person, once. Your backend asks for it with a developer key.
curl -s localhost:7400/v1/runs/$RUN/approvals -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \ -d '{"end_user": "user_7"}'| Field | Meaning |
|---|---|
| end_user | Who the link is for, in your product’s terms. Kept with the decision. Default: the run’s end_user. |
| approver | An 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_in | Seconds the link works, from 1 to GATEWAY_APPROVAL_TTL. Default: GATEWAY_APPROVAL_TTL. Out of range: 400. |
{ "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_TTLis 1 day by default and is the most a link can last. - A bearer link. Whoever holds it decides, unless it names an
approverorGATEWAY_OIDC_REQUIREis 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.
<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.
| Attribute | Meaning |
|---|---|
| base | The gateway’s address, as the user’s browser reaches it (GATEWAY_PUBLIC_URL). |
| token | The approval token (cga_...). Changing either attribute loads the change again. |
| Event | detail | When |
|---|---|---|
| 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 variable | Sets | Default |
|---|---|---|
| --chronos-accent | The colour of the main button and of focus rings. | Lime, #c8ff2e |
| --chronos-on-accent | The text on the main button. | Near black; white when the page set its own --chronos-accent |
| --chronos-radius | Corner radius. | 2px |
| --chronos-font | The font. | The system’s |
<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.
| Call | Body | Answers |
|---|---|---|
| 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/approve | decision (approve or reject), reason, skip_read_check | The run’s new status: {"status": "merged", "merged": n} or {"status": "rejected"}. |
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.
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 examplehttps://gateway.example.com/sso/callback. Give it theopenid,emailandprofilescopes, and agroupsclaim if you allow by group. Note its client ID and secret.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-approversSend 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.
| Setting | Default | Meaning |
|---|---|---|
| GATEWAY_OIDC_ISSUER | unset | Your 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_ID | unset | The gateway’s client at your provider. Needed with the issuer. |
| GATEWAY_OIDC_CLIENT_SECRET | unset | Its secret. Needed with the issuer. Sent with HTTP Basic (client_secret_basic). |
| GATEWAY_OIDC_ALLOW | unset, required | Who 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_ADMINS | unset | Who may sign in to the console and change settings, in the same form. They may also approve. |
| GATEWAY_OIDC_GROUPS_CLAIM | groups | The ID token’s claim that lists a person’s groups (roles with Entra ID app roles). |
| GATEWAY_OIDC_REQUIRE | off | on: every approval link needs a person on the allow list, signed in. Off: only links made for an approver. |
| GATEWAY_OIDC_SESSION_TTL | 12h | How 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/approvalstakes"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
approveremail 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=onmakes 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, andSecurewhenGATEWAY_PUBLIC_URLishttps://. The gateway keeps only its hash. - The person is checked against the allow list on every request. Removing someone from
GATEWAY_OIDC_ALLOWand 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, orselect_accounton 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.
| Call | Answers |
|---|---|
| GET /sso/login | 302 to your provider’s sign-in. ?next=/approvals names a path of the gateway’s to come back to. |
| GET /sso/callback | Your 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 /approvals | The 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/approval | An 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 through | approved_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.
| Code | Status | From | Meaning and what to do |
|---|---|---|---|
| stale | 409 | approve, the link | The run’s changes changed since they were shown. Look at them again, then approve with the new version or make a new link. |
| reads_changed | 409 | approve, the link | What 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. |
| conflict | 409 | approve, the link | Rows the change touches changed in the database. Nothing was written. Settle it with a developer key or in the console. |
| window_passed | 409 | approve, the link, Chronos Cloud | From 0.4.1. A strict change whose window ran out. Nothing was merged. Reject it; the agent proposes again. The error carries strict. |
| strict_target | 409 | approve, the link, Chronos Cloud | From 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, ... | 409 | approve, reject, approvals, the link | The 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”. |
| invalid | 401 | the link | The approval token is not one the gateway knows. |
| used | 409 | the link | The link was already used to decide. Make a new one if the change is still held. |
| expired | 410 | the link | The link’s time ran out. Make a new one with POST /v1/runs/:id/approvals. |
| sign_in | 401 | the link, /v1/me | The change is for a person signed in. The error carries login, where to sign in. |
| not_yours | 403 | the link | The change was put to another person than the one signed in. |
| not_allowed | 403 | sign-in | The person signed in at your provider, and neither GATEWAY_OIDC_ALLOW nor GATEWAY_OIDC_ADMINS names them. |
| no_sso | 404 | /sso/..., /v1/me | Single sign-on is not set up (GATEWAY_OIDC_ISSUER). |
| origin | 403 | /v1/me/runs/:id/approval | The request came from another site’s page. Open the gateway’s pages at GATEWAY_PUBLIC_URL. |
| sso_provider | 502 | sign-in | The identity provider could not be reached or answered wrongly. |
| sso_token | 401 | sign-in | The ID token was refused: its signature, issuer, audience, expiry or nonce. |
| sso_person | 403 | sign-in | The 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_admin | 403 | the console | Signed 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.