The REVIEWIT API

01In a nutshell #sec_decf73bd

The REVIEWIT API exposes campaigns, decisions, evidence, and the audit trail to your own tools — in read-only mode, under a machine identity authenticated by certificate, and without ever allowing a review decision to be made.

02The problem #sec_148ec0fa

A recertification campaign does not live in isolation. Its results are of interest to other systems: the risk governance tool that consolidates controls, the SIEM that correlates security events, the decision-making tool that tracks indicators, the service management that triggers remediations.

Without a programmatic interface, these exchanges are done through manual exports: someone downloads a file, deposits it somewhere, and does it again the following month. Three defects arise from this, all well-known:

Freshness. A dashboard fed by hand is false most of the time.

Traceability. A file that passes through an email box no longer has a certain origin, nor a guarantee of completeness.

The human cost. The time spent transporting data is time that is not spent examining accesses.

03The approach #sec_63100d97

We read everything. We decide nothing.

This is the founding rule of the API, and it is the exact counterpart of the principle that governs the administration surfaces: the administrator approves nothing.

No review decision via API

It is impossible to certify, revoke, or set an exception through a programmatic call. This is not a feature postponed for later: it is a principled exclusion.

A recertification decision derives its entire value from its accountability to a person who has looked, judged, and is responsible for it. A decision produced by a script has no author — at best, it has an operator who launched the script, which is not the same thing. Opening this door would amount to allowing the certification of an entire park in a single query, and reducing to nothing the probative value of all other decisions in the system.

The API is therefore used to exploit the results of the control, never to fabricate them.

The subscription comes from the token, never from the call

No call includes a parameter designating the client, the subscription, or the scope to be queried. The scope is derived from the identity of the presented token.

The consequence is that there is no request, even malformed, even malicious, that can return the data of another client. One does not protect oneself from a parameter error: one removes the parameter.

Certificate authentication is mandatory

The calling systems do not authenticate with a shared secret, but with a certificate: they sign their token request with their private key, which REVIEWIT verifies with the declared public key.

The difference is concrete. A shared secret is a string of characters: it circulates, is copied into a configuration file, is found in a code repository, and once disclosed it is usable by anyone. A private key never leaves the calling system — there is nothing to intercept.

04How it works #sec_ad3e5605

API clients

Each system authorized to call the API is declared as a client, attached to a subscription, with its own permissions. Management is done from the Subscription Manager, and the ability to open the API depends on the subscribed edition.

These clients are distinct from the connections that REVIEWIT uses to collect data from the client. These are two opposing notions — one enters, the other exits — and confusing them would mean that a read access on the API inherits collection permissions.

Permissions

A client does not receive « the API »: it receives a set of permissions corresponding to the domains it needs. A SIEM connector that only consumes the audit trail does not obtain access to signed evidence.

Pagination is mandatory

All collections are traversed by cursor: each response indicates where to resume. This is not a comfort detail.

Pagination by page number becomes false as soon as the data moves during traversal — some elements are seen twice, others never. On a compliance export, this means incomplete evidence without anyone noticing. The cursor eliminates this class of error.

The contract is fixed, and verified

The interface specification is locked by an automated test. Any unintentional modification of the contract — a renamed field, a changed type, a response whose form evolves — fails the integration chain before publication.

This is what allows us to commit to the stability of the interface: it is not guaranteed by good intention, but by a mechanism that refuses accidental change. Breaking changes go through a new version.

05What the API exposes #sec_0de57e12

Three points deserve to be detailed.

Decisions are standardized. The internal states of the product are translated into a stable and documented public vocabulary. An evolution of the internal operation does not break customer integrations.

Proofs are not stored. The certificate attesting to a review is produced at the moment it is requested, from the data of the trail, and then electronically signed. Nothing is kept in advance. The consequence is important: a proof downloaded today reflects the verifiable state today, and is not a fixed document whose freshness would be unknown. An undecided review does not produce proof—it produces an explicit refusal.

The audit export is designed for continuous flow. It works by advancing on a cursor, and adopts a protective semantics: as long as events come out, the next position is provided; when there is nothing new, no position is returned and the consumer keeps theirs. A collection system that queries every minute therefore never loses its place, even if it restarts.

06What comes next #sec_45c04ae7

Outgoing notifications will rely on the same output mechanism as the product's emails. This is not a trivial implementation choice: it guarantees that a webhook and a notification describe the same event, at the same time, with the same delivery guarantees—rather than two concurrent paths that would eventually diverge.

Administrative writes will allow campaigns to be managed from a third-party tool: create, launch, close. They will remain strictly administrative.

The review decision, however, will never be exposed—at any version.

07An open, assumed point #sec_10c3ba42

Consumption quotas are partially handled. A limitation of the instantaneous flow protects the service today, but the quotas per period and per edition are not yet arbitrated: it is a commercial decision as much as a technical one, and it is identified as such.

This document mentions it rather than giving the impression of complete coverage.

08To remember #sec_9a930c7a

The API responds to a simple request—our compliance data must live in our tools—without compromising on what makes the product valuable.

It is open for reading on everything the system produces, closed on what must remain a human act. It authenticates its callers by certificate, derives their scope from their identity rather than asking them, paginates by cursor to never lie about completeness, and guarantees its contract by a test rather than by a promise.

An integration must never become a way to do faster what the control requires to be done carefully.