Docs menu

Provenance

Goal: Set up where your workspace keeps its record of changes, and for how long.

This window opens as a panel: it floats at the right at first, docks anywhere, and keeps your place when you move it. See Node editors and work windows as panels.

Provenance is the workspace's record of changes, kept in storage in your own Azure subscription. What it records, and what it does not, is set out in the Compliance Matrix. This window sets up the storage: its region, its retention periods and its signing setting. It is also where you choose how firmly the storage is held: it starts Protected, and you can later press Lock permanently (see Storage level).

Before you start

  • A connected cloud and a provisioned private landing zone. Until both exist the menu has no Provenance.
  • The region list comes from your connected subscription. If it is empty, check the cloud connection, then Reload regions.

What the window shows

The window, titled Provenance, is one column: Latest deployment, the health of what it built, Record retention with a status badge, Storage level, any pending proposal, the settings, Provisioned details once it is provisioned, the save button, History and, once provisioned, Activity.

Status badgeMeans
Not Configured"No Provenance storage has been provisioned for this workspace."
Provisioning…"Storage was requested. Policy state has not been reported yet."
ProtectedRecords are held under a time-based immutability policy that is not locked. See Storage level
LockedRecords are held under a locked time-based immutability policy, which nobody can remove, including Fathym and Microsoft

Storage level

Every Provenance starts Protected. You decide whether it ever becomes Locked; the environment does not decide for you.

LevelWhat it meansHow you get there
ProtectedThe storage holds an unlocked time-based immutability policy. Records cannot be edited or deleted while their keep period runs. An admin can still change or remove the policy in AzureEvery Provenance starts here
LockedAzure's locked policy. It is never undone, by anyone, Microsoft included. Keep periods can then only be extended (Azure allows five extensions in all)Lock permanently, in this window

The Storage level section shows the level your storage is at now. It is read live from Azure, the same read that reports Provenance's health, not from a setting OpenX keeps. A workspace whose storage was locked before this window offered the choice shows Locked; nothing was migrated. If the level has not been read yet, the section says so and offers no button.

Lock permanently

On a Protected workspace, a person with the right can press Lock permanently.

  • Who can. Only a holder of the access right Workspace.Provenance.Lock. Workspace owners hold every right automatically; anyone else gets it through an access configuration (see Permissions). Without the right the section shows the level and no button.
  • The confirm. The window says plainly that locking cannot be undone, and keeps the button off until you type the workspace name exactly (spaces at either end are ignored; a different letter or case does not match).
  • What happens. The lock is first written to Provenance as a record (it appears in the Activity Log), and that record is written before the lock itself. Then every container of the workspace's Provenance storage is locked at its current keep period.
  • After it. A Locked workspace never offers a way back to Protected; the window has no control that changes the level. New scopes, such as studies, made in a Locked workspace are locked too. In a Protected workspace they are not.
  • Archiving. A Locked workspace cannot be archived, because its containers can never be deleted. A Protected one can be retired as before (see Removals).
  • AI. Thinky and other AIs on the MCP server never lock Provenance. It is a person's act, in this window.

Starting Protected and locking later is deliberate: you can set Provenance up, learn how it behaves, and take the permanent step when you are sure. Locking is what some audit and records rules ask storage to hold; OpenX gives you the controls to help meet them, and the Compliance Matrix says where each one applies.

The settings

Data residency

FieldWhat it does
RegionWhere the storage lives ("Select a region..."). Required. Fixed once provisioned
May data cross geography?Off by default. On shows Replication target
Replication targetA second region. Required when the switch is on. Set only before provisioning

Retention

Retention periods can be extended later. On a Locked workspace they can never be shortened. Three cards, each with a period and a basis:

CardCovers
Domain records"Default for a new scope. A scope may override this while it remains open."
Access control"Team membership, access grants and permission changes."
Platform configurationThe record of the configuration itself

Each period is one of 7 years (2,555 days), 15 years (5,475 days), 30 years (10,950 days) or Indefinite (146,000 days). Platform configuration must be at least as long as the longer of the other two, so the window raises it for you and disables the shorter choices.

Each card has a Basis: "Your stated reason this period applies — shown to auditors exactly as written." Fathym never fills it in for you.

The first time a card goes to Indefinite, the window asks you to confirm: indefinite retention can never be shortened once a container policy is locked, not by you, not by Fathym, not by Microsoft.

Signing

Signing is moving to a login made for each record and meaning, used once. How an app signs that way is in the draft Sign records from your app; what each party owns is in the draft Validation Pack.

Who stamps a signature

The top of the Signing section chooses whose login stamps a signature. It is saved with Save configuration, like the rest of the window.

PartWhat it does
Signing App IdentityOne of the App Identities this workspace trusts. "Signers sign in through your app at this App Identity's login. The login's sealed stamp names the record and the meaning, and OpenX checks it with that login system's public keys. OpenX never calls the login system and never sees a password." It reads Not chosen until you pick one
Proof"A login through (the App Identity's name), tied to the record". Personal signing key: coming is shown and cannot be picked yet
Freshness window"How long ago the signer's login may have happened when they sign. A meaning below may ask for a shorter window, never a longer one." From 1 minute to 1 hour; 15 minutes when the workspace never set one
By meaningOne row per meaning the workspace offers. "A meaning can only ask for more than the workspace: a shorter window, or two people." Each row offers The workspace's window or a shorter one, and Two people (on and fixed when the workspace already asks for two)

If no App Identity is trusted yet, the section says "No App Identity is trusted in this workspace yet, so no login can stamp a signature. Set one up in App Identity and trust it in API Manager, then pick it here." and offers Open App Identity. A pick that is no longer trusted says so by name: "(lookup) is no longer a trusted App Identity in this workspace. Pick one that is."

A save the rules refuse lists the reason beside the part it is about:

CodeMeans
SIGNING_APP_IDENTITY_NOT_TRUSTEDThe App Identity is not one this workspace trusts. Pick a trusted one, or trust it in API Manager first
SIGNING_MEANING_LOOSENSA meaning's rule asks for less than the workspace: a longer window, or one person where it asks for two
SIGNING_MEANING_NOT_OFFEREDA rule names a meaning the workspace does not offer when signing
SIGNING_MEANING_REPEATEDTwo rules for one meaning. Merge them

Thinky and agents can propose the window and the meaning rules, and only to tighten them. Only a person picks the Signing App Identity.

Coming: today a signature with no tied login still goes through, and the App Identity you pick here is not yet what signing checks. When signing moves over, only a named person signing through this App Identity's login signs; a signature with no proof, or made with an OpenX (Team) sign-in, is refused with PROOF_REQUIRED or SIGNER_LOGIN_NOT_TRUSTED, and a workspace with no App Identity picked with SIGNING_APP_IDENTITY_NOT_SET.

Ask before signing

Before a person reaches the "you are signing this" moment, your app can ask whether they may sign at all: POST /ox-api/provenance/signatures/check with the meaning and the record type. No record or digest is needed, and asking writes nothing: no challenge is issued, no login is used, and no refusal is recorded.

  • Allowed: the answer says which proof forms to use (Nonce first, Challenge where the record is written before the signature) and which login to run: the login system's address and client, the scopes, a fresh login every time (prompt=login), and the freshness window in seconds.
  • Not allowed: the answer carries the same code and status the signature itself would be refused with, and a sentence saying how to fix it: a job, an app acting as itself, a connected app naming a person, an assistant acting for a person or a token OpenX made (JOB_SIGNATURE_REFUSED, SIGNER_NOT_A_PERSON with its reason); a person not signed in through the workspace's trusted login (SIGNER_LOGIN_NOT_TRUSTED); no Workspace.Provenance.Sign (ACCESS_RIGHT_REQUIRED); a meaning the workspace does not list (SIGNATURE_MEANING_NOT_CONFIGURED).

How an app uses the answer is in Ask first.

Signing with a login tied to the record

A signature can carry its proof: the ID token from a login made for this record and meaning, and the salt the app made its nonce with. OpenX recomputes the nonce from the record as it stores it, so a login made for one record or meaning cannot sign another. It then checks that the login is the signer's own, that it is inside the freshness window, that it carries the signer's name (the printed name on the signature), and that it has not signed before: each login signs once.

An app that writes the record as part of the act asks OpenX for a signing challenge first and logs the person in with it; the signature then carries the challenge in place of the salt, and the challenge signs once. Several records shown as one list sign together under one login, all or none. How an app does each is in Challenge form and Batch.

A proof that fails any check is refused and nothing is written:

CodeMeans
LOGIN_NOT_FOR_THIS_RECORDThe login was made for a different record or meaning. Start a new login for this one
LOGIN_ALREADY_USEDThis login has signed once already. Sign in again
LOGIN_TOO_OLDThe login is older than the freshness window. Sign in again, then sign straight away
LOGIN_NOT_THE_SIGNERThe login belongs to someone else. The person signing signs in themselves
PROOF_NOT_FROM_LOGIN_SYSTEMThe token was not issued by the login system this workspace trusts for signing
PROOF_HAS_NO_NAMEThe login carries no name. Turn on the name claim in your login system's app registration
PROOF_MALFORMEDThe proof needs the ID token and either a salt of at least 16 random bytes or a challenge
CHALLENGE_EXPIREDThe signing challenge ran out (after 15 minutes) or is not known. Ask for a new one
CHALLENGE_SPENTThe signing challenge has signed once already. Ask for a new one

For now the token's audience must be the trusted App Identity's own client. The nonce and the steps an app follows are in Nonce form.

Signature certificate

GET /ox-api/provenance/signatures/certificate prints the signatures on one record, or in one ceremony: pass ceremonyId, or targetType with targetRecordId, the same ways in as reading signatures. It answers a page with one section per signer: the printed name, the title, the account, the meaning, the time in UTC, the record, its BindingDigest, whether the link to the record still holds, the seal and whether it checks, the proof form, the login's time and methods, the issuer, the app's client and the comment. A field a signature does not carry prints as "not recorded", never filled in: signatures made before a field existed lack it. The page is text only, never an image of a signature, and loads and runs nothing else, so your app can embed or print it. Add format=json for the same certificate as JSON. It needs Workspace.Provenance.Read, the right an auditor reads the record with.

Signing in again

Sign in again to sign:

ChoiceWhat it does
OffA signature uses the signer's existing sign-in. A connected app that signs for a person still asks that person to sign in again once per session
Once per signing sessionThe first signature in a session asks the signer to sign in again. Later ones in that session do not, until the sign-in is older than the freshness window
Every signatureEach signature asks the signer to sign in again first. This is the default

A workspace that never chose a setting gets Every signature. This one setting covers every way a person signs: in OpenX and through a connected app such as Sample Management, which follows it.

Who the signer signs in again with depends on where they sign. Signing in OpenX, they sign in again with their OpenX sign-in. Signing through a connected app, they sign in again with the directory that app is connected to in App Identity. Either way the sign-in must be the signer's own: a different person's sign-in is refused.

Signing in OpenX, signing in again takes you to OpenX's sign-in page, which asks for your password even though you are already signed in. When you finish, you come back to the page you were on and the signature goes ahead. If you cancel, or a different person signs in, you come back with nothing signed.

What a signature holds

Each signature stores who signed (SignedBy), the signer's printed name when their sign-in-again gave one (SignerPrintedName, from the sign-in's verified name, never the username), when (SignedAt, server time, UTC), what the signature means (Meaning, from the workspace's list), and the record it signs, with a digest of that record as stored (BindingDigest). When the signer signed in again, the time and methods of that sign-in are kept too (StepUpAt, StepUpMethods).

Each signature is also sealed with a key that belongs to the workspace alone, kept in the workspace's own Azure Key Vault. The key is made the first time a signature needs it, and it can sign but can never be exported. If the vault cannot be reached, the signature is refused and nothing is written. An auditor can check a seal without OpenX: GET /ox-api/provenance/signatures/seal-keys gives the public halves of the key (see Activity Log).

Two people

With the two-person rule on, a ceremony needs two different people. A second signature by the same person is refused (TWO_PERSON_SAME_SIGNER), and so is a signature joining a ceremony for a different record (TWO_PERSON_DIGEST_MISMATCH). Nothing is written in either case.

Signature events

Signature events tells your own systems when a signature happens. Add a subscription with an HTTPS address, choose which events it receives (Signed, Refused, LinkChanged) and give it a secret, typed or generated. The secret is kept in the workspace's own Key Vault, and the window never shows it again. An address that is not HTTPS, a subscription with no event chosen, and one with no secret are refused when you save, each with the reason. Only a person can set this up: an agent's proposal that carries a subscription is refused.

Delivery is at least once. A failed delivery is tried again, 5 seconds, 30 seconds and 2 minutes after the last try; after that it is a dead letter, which the window lists with the newest deliveries (the newest 100 per workspace, kept for 30 days). Each delivery is signed so your receiver can check it came from your workspace. How a receiver checks it is in Sign records from your app.

Save configuration

NOTE

"Saving provisions immediately. This creates the storage account, containers and retention policies in your Azure subscription before the save returns — there is no separate deploy step. Retention periods can be extended later."

Save configuration is enabled once a region is set (and a replication target, when the switch is on), and no retention period is shorter than the stored one. On success: "Saved. Azure provisioning ran as part of this save." The badge changes once the window reads the stored record back. A new Provenance is always saved Protected; saving never locks it. Only Lock permanently does, and a locked policy can never be shortened or removed.

Provenance is never removed. Saving the configuration does not wait for Deploy; adding back a retired audit trail does (below).

Activity

Once Provenance is provisioned, the window shows Activity: "Every change Provenance recorded on this trail, newest first. Commit history already shows who changed what and when; this is the extra copy, chained so a change to any record shows when the log is checked."

  • Trail. Pick which record to read: Workspace changes, Access changes, or a study's records (Study records: and the study). Each line shows when, then what changed. Show older reads the next 25. A trail with nothing on it says "No activity yet."; a read that failed says why instead, never "No activity yet."
  • A change. Press a line to see This record's history: each field before and after, as Provenance recorded it. A correction shows its reason and the fields it changed. "Older changes to this record exist." means there is more history than one read shows.
  • Export CSV and Export JSON save the trail under the file name Provenance gives it ("Saved (file name)."). If the export reached its limit, it says "The file stopped before the end of the log: it holds the newest records one export can carry." A refused export saves nothing and says why.

Check the log checks the newest stretch of the trail; Check the whole log (slower) reads every record on it. Each answer says what was checked ("Checked the whole log", or which records) and when the check before this one ran. There are four answers, each drawn its own way:

AnswerMeans
The log is intactEvery record checked follows the one before it
The log has been changed"Record (n) does not match the record before it."
Two records claim the same place in the logTwo records follow the same one. The answer names where
Nothing was checked"The log holds no records in this range, so nothing could be verified. This is not a pass."

Reading the trail outside OpenX, and filtering it, is in the Activity Log.

A retired audit trail

A retired audit trail shows "This audit trail is retired", with how long its records are kept. It takes no new records; its records can still be read, exported and verified. Add it back asks first: nothing happens until Deploy. Confirm, then save: the next Deploy checks every record chain against the record written when it was retired, writes a record saying it was added back and by whom, and the workspace records its audit trail again. Records written while it was retired are listed in that record. Forwarders removed when it was retired are not restored by it.

Rights

Save configuration checks no access right beyond being in the workspace. Lock permanently needs Workspace.Provenance.Lock, which workspace owners hold with no access card; everyone else needs it granted in an access configuration.

Signing, and signing in again to sign, need Workspace.Provenance.Sign. Owners hold it; everyone else needs it granted in an access configuration. Signing in again for another purpose, such as approving a data store unlock, does not need it. Reading the seal keys needs Workspace.Provenance.Read, the right an auditor reads the record with.

Thinky and agents

Thinky and agents can propose Provenance settings, including policy settings this window has no control for (reason categories, signature meanings, approval and two-person rules). The region and replication target only before it is provisioned. A proposal may extend a retention period, never shorten it, and may tighten the signing setting, never weaken it. Locking the storage is not a setting and is never proposed: an AI on the MCP server cannot lock Provenance. It is a person's act in this window.

A pending proposal shows in the window as a table of current and proposed values; rows an accept would refuse are marked. "A pending proposal is not included in this Save — accept it first." Accept it in Proposals, then save. The Provenance menu item counts pending proposals.

Messages you may see

Code or placeMessage or meaning
PRIVATE_LANDING_ZONE_REQUIRED"This needs a private landing zone, which this workspace does not have yet."
The retention floorPlatform configuration is shorter than the longer of the other two. Raise it
ShorteningA period shorter than the stored one is refused, and the list shows what to put back
ACCESS_RIGHT_REQUIREDLock permanently was pressed by someone without Workspace.Provenance.Lock. Nothing was locked
PROVENANCE_LOCK_NAME_MISMATCHThe name typed does not match the workspace name. Nothing was locked
PROVENANCE_ALREADY_LOCKEDThe storage is already Locked. Nothing changed
A refused saveThe server's reasons are listed under the explainer
A failed provisionThe platform's reason, or "Azure provisioning did not complete, and the platform did not report a reason."
DEPLOY_IN_PROGRESSA setup window or a Deploy is already running for the workspace. Wait for it to finish, then try again
PROVENANCE_NOT_PROVISIONEDA Provenance call before this window has been saved: "Provenance storage is not provisioned for this workspace."
REAUTH_REQUIREDThe signer must sign in again before this signature. Sign in, then sign
REAUTH_REFUSEDThe sign-in again was not accepted, for example it was someone else's. Nothing was signed
STEP_UP_PROVIDER_UNAVAILABLEThere is nowhere to sign in again. In OpenX the reason is OPENX_SIGN_IN_NOT_CONFIGURED: this OpenX's own sign-in is not set up. Through a connected app it is NO_CONNECTED_APP or PROVIDER_NOT_READY. Nothing was signed
ACCESS_RIGHT_REQUIRED (signing)The signer does not hold Workspace.Provenance.Sign. Nothing was signed
TWO_PERSON_SAME_SIGNERWith the two-person rule on, the same person signed twice. Nothing was written
TWO_PERSON_DIGEST_MISMATCHWith the two-person rule on, the signature joins a ceremony for a different record. Nothing was written
SIGNATURE_SEAL_UNAVAILABLEThe workspace's Key Vault could not be reached to seal the signature. Nothing was written; try again

Next steps

On fathym.com: OpenX provenance →

On this page