Set up automatic journal PDF storage

This guide is for the developers and IT staff connecting your company’s system to NotaryCentral. After setup, the notary chooses Finalize selected and your system saves the complete journal PDF automatically. Your company keeps the signer details and the PDFs.

Your PDF service is the program that checks each finalized entry, creates its PDF and saves the files. It runs on your company’s server without someone opening a browser or clicking Download.

1. Who does what

Start with the admin and notary setup handbook for the account screens. Use the API reference for the exact request schemas for your environment.

The file your company needs is journal.pdf. It contains the complete journal entry and its verification cover. Keep the two supporting files, journal.json and manifest.json, so the saved record can be checked later. A receipt by itself is not the complete entry.

Your system -> permitted fields and data hashes -> NotaryCentral Drafts
Notary Finalize -> signed receipt available through the evidence API
Your PDF service -> check the record -> create PDF -> save files -> confirm

2. Get API access

1. In Menu → Settings → API credentials, select the intended workspace under Credential workspace. Confirm workspace API approval; personal approval does not substitute for it.
2. Enable Federated journal integration in Team → Settings → Journal. This is separate from requiring personal Vault/key setup.
3. Create or select one named OAuth client for this integration and workspace. Grant the three permissions below. Keep the one-time client secret in your company's secret manager.
4. On that same client, save the approved origin for your company’s portal, such as https://portal.example.com. Supply record links beneath that exact origin. Existing entries retain their original binding when the setting changes.
5. Record the workspace ID, client ID, assigned notary IDs, commission IDs and environment API base URL. Use opaque order and tenant references; keep the mapping to real source records in your own system.

The Commit scope does not authorize an integration to personally finalize a company-managed entry. That decision remains in the assigned notary's authenticated session.

Use server-side POST /oauth/token with form-encoded grant_type=client_credentials, client_id, client_secret, a space-separated scope containing the three names above, and audience notary-public-api. Keep access tokens and secrets out of browsers, record URLs and support logs. Renew tokens before expiry; a rejected token can be renewed and retried once. Repeated denial needs diagnosis of the client, workspace and scopes, rather than switching to a notary's login.

3. Set up each notary’s journal key

Each notary completes private journal setup. Your integration team then calls:

POST /api/public/v1/federated-journals/custody/keys/lookup
Content-Type: application/json
Authorization: Bearer <integration-access-token>

{"notaryUserIds":["user_assigned_notary"]}

Require the expected workspace, notary and a READY result. Use its public encryption key and key ID. Your PDF service never needs the notary's private key, passphrase or recovery kit. If enrollment is missing, stop protected creation until the notary completes it.

When you prepare an entry, save an exact copy of its data, a fresh cryptographic salt, its images and the assigned encryption key ID in your own system. Do not rebuild an old snapshot from today's source record: a later address or document change must not alter an already committed version.

Use the versioned schema, shared cryptographic helpers and conformance fixtures supplied for the integration. For NCJ-PII-COMMITMENT-V2, commit the exact retained UTF-8 bytes and their length. Do not normalize or reserialize them after commitment. Encrypt the separate notary copy to the enrolled public key; keep that encrypted package in your company’s storage as well.

Provision the verifier's trusted public root through the approved release/configuration channel. A key arriving inside an untrusted receipt or HTTP response cannot establish its own trust. Never substitute a private root or signing key.

4. Send a test entry

For company-managed journals, use CUSTOMER_HELD in API requests. Some endpoint names below contain customer-held. Copy those names exactly; the API still uses them.

Send one fictional entry before using real records. Your server makes the requests below in order, using the same workspace API client. The API reference contains the complete request bodies.

When an endpoint requires Idempotency-Key, reuse the same value when retrying. Resend the same version, digests and key ID for protection and staging requests. If the connection drops, check whether the entry was already saved before creating another. Always set custody_mode to CUSTOMER_HELD for company-managed journals; omitting it selects a different storage workflow.

The metadata requests accept only permitted metadata, identifiers and cryptographic bindings. The custody batch request separately stores the encrypted notary copy in NotaryCentral. Never send plaintext snapshots, salts, signer fields, private credentials or a completed PDF. Salt and signature images belong inside the encrypted envelope, not in separate request fields. Unknown fields are rejected; do not use free-text fields to carry source data.

Finalization requires this independent encrypted copy. After finalization, the notary can reopen the complete entry from their personal account even after leaving your company or losing access to your systems. The secure viewer retrieves the stored ciphertext and signed evidence from NotaryCentral and decrypts it locally with the notary’s private journal passphrase; it does not contact your portal.

Expected result: the entry appears in the assigned notary's commission under Journal → Drafts. Staging runs through the API. The notary makes the Finalize decision in NotaryCentral. The notary can inspect source records through Entry Details → View company record and can separately open their protected copy when needed.

5. Check for finalized entries

Configure your PDF service to check signed evidence with the same workspace API client and Read evidence permission. Keep the journal IDs or external order references created by your integration so the service can reconcile them after a restart.

Use GET /api/public/v1/federated-journals/{journalId}/evidence/history for one entry, or POST /api/public/v1/federated-journals/evidence/batch for multiple entries. Batch requests accept either journal_entry_ids or external_order_refs; follow the returned pagination token without changing the selector list.

Queue each finalized receipt and its exact journal version for PDF creation. Pending or rejected entries may have no finalization receipt. Track completed work by receipt ID and version, and preserve retry state across restarts so repeated checks reuse successful output.

6. Create and save the PDF

After the notary chooses Finalize selected, your PDF service performs these steps automatically:

1. Get the signed receipt with GET /api/public/v1/federated-journals/{journalId}/evidence/history, using the Read evidence permission. Select the exact receipt ID and version queued by your evidence check, rather than whichever version is latest when processing runs. Retrieve the signed receipt-key manifest from GET /.well-known/notarycentral-journal-key-manifest.json; its signature must verify against your separately provisioned public root.
2. Load the saved data, salt, images and encrypted copy for that exact version. Use the shared verifier to check the signatures, trusted public key, entry IDs and data hashes. These checks must all pass before creating the PDF.
3. Use the shared PDF generator on your company’s server. It creates the complete entry without opening a browser or sending the data to an outside PDF service. If the entry refers to a signer’s signature, the matching image must be available. Optional fields that were not supplied are labeled in the PDF.
4. Save journal.pdf, journal.json and manifest.json, and confirm that all three writes finished. The supporting files record the entry ID, version, receipt, PDF generator version and file hashes. When retrying, check and reuse the saved files rather than replacing them.
5. Tell NotaryCentral the PDF was saved, using the same API client's Commit permission. Send this request only after the files are safely stored:

POST /api/public/v1/federated-journals/{journalId}/receipt-acknowledgments
Authorization: Bearer <integration-access-token>
Content-Type: application/json

{"receipt_id":"22222222-2222-4222-8222-222222222222"}

This request tells NotaryCentral your company has saved the record. It is safe to retry the same receipt ID. NotaryCentral does not receive or inspect your stored PDF. An acknowledgment must not be sent while rendering, verification or storage is failing.

NotaryCentral signs the receipt that binds the metadata and historical commitment. Your company’s PDF presents the verified record; it is not a PII-filled PDF signed by NotaryCentral.

Choose where to save the files

For the local reference demo, the default destination is:

~/.local/share/notarycentral/customer-journal-demo/archives/
  <journal-id>.v<version>.<receipt-id>.export/
    journal.pdf
    journal.json
    manifest.json

The older standalone JSON file is retained for compatibility. The PDF package is the completed output. The local implementation uses private directories/files, synced writes and atomic directory publication. A deterministic receipt/version identity prevents duplicate output on retries. Previously acknowledged JSON-only records are backfilled with PDFs.

For production, use your own approved object store and credentials. Write and verify all objects, then publish the completion manifest before acknowledging. Configure access for authorized staff, retention, backups and recovery. Do not put real PII in a public bucket or send files through the marketing site. Your IT team manages cloud storage; the reference demo does not create a bucket or grant cloud permissions.

Retry failed or missed entries

Run reconciliation in your PDF service against authenticated evidence history, including entries finalized while the service was offline. Keep durable processing, storage and acknowledgment state. Retry only incomplete work for the same receipt/version; a failed archive does not undo finalization or justify creating another entry.

The local demo checks for unsaved finalized entries every five seconds. A healthy local save normally follows within a few seconds; production timing depends on your queue, rendering workload and storage. Check for a completed PDF package rather than treating a fixed delay as proof of success.

7. Try the local demo

Ask your environment administrator to prepare the app and API, workspace credentials, approved company portal address, private service configuration and trusted public-root.json. The assigned notary must have completed journal key setup before you send the test entry.

The reference PDF service requires Node22.18 or newer, its locked native canvas dependency and installed fonts suitable for your journal text. Validate rendered pages in the deployment environment. From the repository root:

npm ci --prefix tools/federated-journal-customer-demo
node scripts/local-journal-viewer.mjs start
node scripts/local-journal-customer.mjs start
node scripts/local-journal-customer.mjs status

The local reference service is at http://localhost:18716; the isolated personal viewer uses http://127.0.0.1:18715. The operator starts that viewer for private key enrollment/viewing. Neither the demo page nor the viewer needs to stay open for PDF archival. The PDF service needs its running server process, accessible source storage, valid organization OAuth credentials and trusted public root.

The local launcher can read an existing approved OAuth secret reference through 1Password at startup. The PDF service renews access tokens in server memory afterward; there is no per-entry secret prompt. Your server can use your company’s own secret manager instead of 1Password. Your integration’s credentials never include NotaryCentral's database password.

The loopback demo uses authenticated reconciliation for automatic saves. The demo's fixed synthetic company login and loopback-only OAuth helper are not production identity or connectivity components.

8. Check that it works

• Send one fictional test entry, have the notary finalize it, and confirm the PDF/evidence/manifest match that exact entry, version and receipt. Inspect every PDF page, including signature images and continuation headings.
• Leave another draft unselected; it must remain Draft. Repeat an evidence check and verify that the existing PDF and original generation metadata are reused.
• Stop your PDF service, finalize another synthetic entry and close the notary browser. Restart the PDF service; it must recover the PDF and acknowledge without reopening that browser.
• Force a storage failure. The entry stays finalized, but archival acknowledgment must wait. Restore storage and confirm automatic recovery.
• Try wrong-client/workspace access, an invalid receipt signature, altered source bytes and a missing committed signature image. These must not produce an acknowledged complete PDF.
• Check logs and outbound requests for source data, salts, private keys and PDFs. Keep diagnostics to opaque references, version, receipt, phase and safe error codes.

9. Fix common problems

For nontechnical account actions, return to the admin/notary handbook. For output interpretation and synthetic downloads, see Making Sense of a Federated Notary Journal Export. For settings, see PII Custody Boundary Configuration.