Data Access

Use Data Access to bring VeriProof records into your compliance application. Your system retrieves application inventories, runtime oversight records, and saved framework assessments through a shared API.

Records arrive in publications. Each publication contains structured JSON, a matching PDF, and a signed manifest that lets your system verify the files before importing them.

Set up an integration

You’ll need administrator access to integrations and people, along with compliance viewing and evidence export permissions.

Choose the records to share

1. Open Settings → Integrations → Data Access and enter a name for the receiving system or workflow.
2. Select the applications it can read.
3. Choose its datasets and registered frameworks.

New applications and frameworks aren’t added automatically. To expand access later, update both the Data Access selection and the identity’s application permissions in Service principals.

Register a credential

Under Authentication method, choose a signing key or client secret. Use a signing key when your receiving platform supports it.

• Signing key: Generate an ECDSA P-256 key pair in your system. Paste the Public signing key (PEM) and keep the private key in your secret store.
• Client secret: Choose Secret lifetime (days). After registration, save the displayed secret in your secret store before closing the dialog. It’s shown only once.

Select Register integration. VeriProof saves the identity, access, credential, and registration audit together, then starts preparing the first publications.

Check the first publications

Review Initial publications for each dataset and application. A missing saved assessment appears as unavailable. Use dataset discovery to check which registered frameworks support publication.

If preparation stops, check publication history for files already created and select Check and continue preparation. Recovery reuses committed publications. The hourly worker also checks unfinished requests.

For a source that needs attention, correct the source and select Prepare publication. Changing access stops unfinished initial preparation; review the new selection and prepare the required publications manually.

These results remain after you leave the page. Check publication history for current availability, because a previously prepared file may have expired or been withdrawn. Recurring preparation starts only when you enable a schedule.

Finally, copy the token endpoint, client ID, API base URL, and scope into your receiving system’s configuration.

Authenticate

Request a token from /v1/auth/service-principals/token with grant_type=client_credentials and scope=veriproof.data-access.read.

Authenticate with either a registered signing key or a client secret. For a secret, use HTTP Basic authentication or the form fields client_id and client_secret. Use one authentication method per request.

Send the returned token as Authorization: Bearer <access_token> on Data Access requests. Tokens last ten minutes. Keep credentials and tokens out of URLs, logs, source files, and browser storage.

Data Access requires its own integration credentials. Portal sessions, SDK keys, and general VeriProof API tokens aren’t accepted.

Use a signing key

Your first key is registered during setup. To add another, open Signing keys and register its P-256 public key in PEM format. VeriProof displays the key ID, fingerprint, expiry, and assertion audience. You can keep up to five active keys while rotating them.

Sign an ES256 JWT with these fields:

Include client_id, client_assertion, and client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer with the token request fields above. Leave out client secrets and HTTP Basic credentials.

Generate a fresh assertion for every request, including retries. An accepted assertion can’t be reused. The flow follows the JWT client authentication profile , with single-use assertions and a five-minute maximum lifetime.

For the downloadable clients, set these environment variables:

• VERIPROOF_CLIENT_ID
• VERIPROOF_SIGNING_KEY_ID
• VERIPROOF_ASSERTION_AUDIENCE
• VERIPROOF_PRIVATE_KEY_PATH

Leave VERIPROOF_CLIENT_SECRET unset. The private key stays in your system; the client sends a signed assertion.

Rotate or revoke credentials

Register a replacement key or add a client secret, update the receiver, and test a retrieval. Then revoke the old credential. Manage signing keys in Data Access and client secrets in Service principals.

Revoking a signing key also stops reads using tokens issued with that key. Other credentials remain active until you revoke them separately. To stop all further reads, disable the integration.

Data and files

Publications exclude prompts, outputs, source attachments, and owner/reviewer names and user IDs. Application and model labels remain visible, along with source references. An evidence reference doesn’t grant access to the source attachment.

The data.json and report.pdf files use the same selected source facts. Repeated downloads return those retained files without rerunning the assessment. Treat them as snapshots: overlapping reporting periods can contain the same activity.

Reporting periods and limits

Publication history separates the covered period from generation and expiry dates. The period includes its start and excludes its end. For imports, use the signed manifest’s UTC boundaries and each control’s own assessment period.

If a file exceeds its limit, select fewer applications or a shorter reporting period. On HTTP 429, wait for the response’s Retry-After delay.

Expiry, withdrawal, and retention

Expired or withdrawn publications can’t be downloaded. Withdrawal blocks access immediately, but copies already retrieved remain in the receiving system.

An hourly job removes expired archive files and retains publication metadata. Storage failures are retried. Incomplete archives become eligible for cleanup after 24 hours, once preparation has stopped; withdrawn files follow the normal expiry schedule.

Apply your organization’s retention policy to imported copies. Storage-provider backups, versions, and soft-deleted files follow the provider’s settings.

Try the reference receiver

Download the reference compliance receiver to test an import. It stores publications, assessment controls, and their original files in SQLite. There’s no database server to configure.

1. Extract the ZIP and open REFERENCE-RECEIVER.md. You’ll need Node.js 22.13 or later.
2. Set the credential environment variables described in the guide. Save the publisher’s trusted verification key in a separate file.
3. From the extracted folder, run these commands with your API origin and local paths:

node reference-receiver.mjs <API-origin> <receiver-directory> <trusted-public-key.pem>
node receiver-view.mjs <receiver-directory>

Open http://127.0.0.1:3108  to see the imported records. Filter by dataset, open a publication, and compare its control results with the source JSON and PDF.

Run the import again to retrieve later publications. Records you’ve already imported keep their existing receipts, so a retry doesn’t create duplicate controls or files.

The receiver saves each publication, its controls, files, and receipt in one transaction. It then advances its polling position. Read requests retry HTTP 429 and 503 within the limits described in the guide.

To connect your application, replace the SQLite import transaction with your destination’s transaction. The receiver guide explains credentials, storage, recovery, and adaptation. Keep reviews and compliance decisions in your application’s existing workflow.

Read endpoints

Download the OpenAPI contract for request fields and response schemas. Use the API origin displayed in the portal.

Start with GET /v1/data-access/datasets to discover permitted applications, datasets, formats, and limits. Add ?applicationId=<id> to check framework availability for one application. Discovery checks the source without preparing a publication.

Use GET /v1/data-access/assessments?applicationId=<id>&frameworkId=<code> to list published assessment revisions. Both filters are optional. Results include the source assessmentEvaluationIds and the export’s publicationId.

Work through listing pages

Choose an initial page size from 1 to 100. While hasMore is true, continue with nextCursor, even if a page is empty. Access filtering can leave a page with no records.

Keep filters unchanged while following a cursor. Save a separate position for each filter combination, and don’t reuse an assessment cursor on the general publications endpoint.

Save the next position after processing the records. When you reach the end, poll from that position later. Use hasMore to check for more pages, rather than comparing cursor strings. Their signatures include an expiry time.

Cursors are tied to the integration and its effective permissions. If access changes or a cursor expires, restart the listing and use publication IDs to recognize previously processed records.

Listings retain expired and withdrawn metadata, with no downloadable files for those states. Withdrawals receive a new listing position so polling systems can find them. Expiry alone doesn’t create a new position; check availability again before a delayed import.

Handle read errors

Example request and response

After authenticating, list publications and use a returned publicationId to inspect one revision. Replace the example ID below with your own.

GET /v1/data-access/publications/11111111-1111-4111-8111-111111111111 HTTP/1.1
Authorization: Bearer <access_token>
Accept: application/json

An available saved assessment returns a summary such as:

{
  "publicationId": "11111111-1111-4111-8111-111111111111",
  "datasetId": "framework_assessment",
  "frameworkCode": "NIST_AI_RMF",
  "applicationIds": ["22222222-2222-4222-8222-222222222222"],
  "generatedAt": "2026-10-29T19:28:00Z",
  "expiresAt": "2026-11-28T19:28:00Z",
  "availability": "available",
  "files": ["manifest.json", "data.json", "report.pdf"],
  "assessmentEvaluationIds": ["33333333-3333-4333-8333-333333333333"],
  "correctsPublicationId": null
}

Download each file through GET /v1/data-access/publications/{publicationId}/files/{fileId} with the same authorization header. For example, use data.json as the file ID.

The summary tells you whether files are available. The signed manifest and JSON contain coverage dates, source details, and verification information. Verify the files before importing them. Expired or withdrawn summaries have an empty files list.

Verify and process safely

Download the pull client and verification utility into the same folder. Both use built-in Node.js modules.

Configure the signing-key environment variables, or set VERIPROOF_CLIENT_ID and VERIPROOF_CLIENT_SECRET from your secret store. Supply a new destination directory and a separately trusted verification key:

node pull-publication.mjs <API-origin> <publication-id> <new-directory> <trusted-public-key.pem>

The client downloads one publication, verifies its files, and checks availability again. It requires HTTPS outside loopback development and refuses redirects. Leave partial files from failed pulls out of your import process.

To verify files you’ve already downloaded, run:

node verify-publication.mjs <publication-directory> <trusted-public-key.pem> <publication-id>

If you’re writing your own verifier, decode the manifest’s payloadBase64 and verify those exact bytes with its ECDSA P-256/SHA-256 signature. Don’t parse and reserialize the payload first. Then check the publication ID, application scope, file lengths, and SHA-256 hashes.

A valid signature confirms that the files match what the trusted publisher signed. Your application still validates the source records and routes them for review. Save an import receipt after the destination transaction commits, so retries can recognize work already completed.

Schedule publications

Open Publication schedule, choose Daily or Weekly, and select Enable schedule.

The worker checks hourly. It prepares inventory and runtime snapshots when their interval is due, and checks saved assessments for each selected application and framework. A snapshot can arrive up to an hour after its interval ends.

Saved assessments are published once per eligible source revision. The schedule doesn’t run a new assessment or republish an unchanged one after expiry or withdrawal.

Review the latest check for prepared files, unchanged sources, snapshots not yet due, and sources needing attention. If a check stops early, some sources may have no result. Check publication history before preparing files manually; an enabled schedule retries at its next hourly check.

Changing access requires you to review and enable the schedule again. Publishing also pauses if the authorizing administrator loses the required role or application access. Pause schedule stops future preparation and leaves existing publications available.

The panel shows the latest check, rather than a full attempt history. Saving a schedule clears that result. If no supported sources match, use dataset discovery to review the selected applications and frameworks.

Your system retrieves the files by polling or responding to an availability notification. A listing cursor tracks publications; it isn’t an incremental feed of changes to their underlying records.

Choose an application and reporting dates

For a manual assessment, select the framework dataset and choose Assessment application. The list contains granted applications with that framework registered. You can prepare separate assessments for several applications within one integration.

For inventory or runtime snapshots, leave both dates empty to use the defaults. Inventory observations cover 30 days; runtime activity covers seven days. To choose another period, enter both Start date and End date (inclusive).

Inventory dates use the organization’s reporting time zone; runtime dates use UTC. The inventory is still a snapshot of current settings. Its date range limits observed activity, rather than reconstructing past application settings. All data is bounded by the preparation cutoff. Scheduled snapshots use the default periods.

Correct an earlier publication

In Publications, select the dataset and applications, then choose Earlier publication to correct (optional). Review the dates and select Prepare publication.

The list contains matching records on the current history page. Corrections must use the same integration, dataset, framework, and applications. You can reference an expired or withdrawn publication.

The correction receives a new ID and files, with correctsPublicationId linking back to the earlier publication. That earlier version remains downloadable until it expires or you withdraw it.

Keep both IDs and their relationship in your receiving application. Reviewers can then decide which evidence to use without losing the history.

Review integration access

Open Settings → Access log and select Data Access request. Authorized administrators can inspect the integration, operation, HTTP status, and relevant publication or file IDs.

The log records the server’s access decision and handled errors after machine authentication. Use your receiver’s import receipts to confirm what reached the destination. Invalid credentials and unexpected internal failures aren’t included in this read-audit record.

Tokens, assertions, cursors, file contents, and arbitrary request paths are excluded. If the audit write fails, the API withholds the data and returns 503, audit_unavailable, and Retry-After: 60. Wait before retrying, and keep your previous polling position until processing succeeds.

Receive availability notifications

Use a webhook when you want a publication to trigger a pull. In Availability notifications, select Configure endpoints and review delivery history.

Register an HTTPS endpoint in Webhook delivery, complete its signed verification challenge, and enable it. Select data_access.publication_available and follow the webhook signature verification guide.

This event covers all Data Access integrations in the organization, regardless of the webhook’s application filter. Match data.integrationId before acting. The notification includes integrationId, publicationId, datasetId, generatedAt, and expiresAt; your receiver uses its own Data Access credentials to retrieve the files.

Validate the signature and timestamp, acknowledge the event promptly, and queue the pull. Delivery attempts can repeat, so use the stable event ID to recognize duplicates. Check publication availability during retrieval because access, expiry, or withdrawal may have changed.

VeriProof saves the publication and pending notification together. It checks subscriptions immediately, and the hourly worker recovers unfinished checks. Only enabled, verified subscriptions that selected the event receive deliveries. Enabling a subscription later won’t replay earlier checks; keep polling to recover missed publications.

The panel shows the latest ten checks. Handed to webhook delivery means a delivery record exists. Open Webhook delivery for attempts, retries, and responses, then check your receiver’s receipt to confirm the import.

Save a polling position

For file retrieval without a SQLite import, download the polling client alongside the pull and verification utilities. Use the same credential settings and trusted public key.

node poll-publications.mjs <API-origin> <polling-directory> <trusted-public-key.pem>

Each run processes up to 100 records. Repeat while more pages remain, then run periodically or when a verified notification arrives. The directory belongs to one API origin and integration ID.

The client saves progress after local processing, resumes interrupted pages, and tracks withdrawals and expiry. Only completed, verified folders are ready for import. Leave .pending folders alone, and recheck availability before importing files later.

Run one poller per directory. After a crash, confirm that the process recorded in poll.lock has stopped before removing that lock. If access changes or the cursor expires, start a new polling directory and reconcile destination records by publication ID.

To include your own import step, pass a callback to the exported polling function. Return only after the destination commits its records. A crash between that commit and the checkpoint can repeat the callback, so reuse the existing import receipt on retries.

The client README has the recovery details and field-mapping checklist.