API keys

An API key lets another of your company's systems —an ERP, a dashboard, a script— read or write in goPrevina through the REST API, without using anyone's account. All calls go to the base path /api/v1.

1. What is on the screen

At the top, the “Create a key” block with the “Name” field, the “Scopes” (“Read”, “Write”, “Lab results (FHIR webhook)” and “Occupational health provider (ingest only)”), the “Reach” selector and the “Create a key” button. Below, the “Per-resource scopes (public API)” drop-down the company's list of keys (if there are none it says “No API keys yet.”) and, at the bottom, “Provider ingests”.

When there is at least one key, four status cards with a count appear above the list: “Expired”, “Expiring in 30 days”, “Revoked” and “Active”. Press one to see only those keys; press it again to see them all.

2. Create a key

1. Enter a “Name” that says who uses it (for example, “Payroll ERP” or “management dashboard”).

2. Tick the “Scopes”: “Read” if the system only reads data; add “Write” only if it has to create or change records. Tick “Lab results (FHIR webhook)” only for a laboratory that sends results over FHIR. “Occupational health provider (ingest only)” is for the key of an occupational health or screening provider in Ireland or the UK: it replaces the other scopes and the reach stays at “This company”. With it the provider sends appointments, fitness outcomes, certificates and screening results (JSON, FHIR R4 or audiometer and spirometer CSV) into your company and reads back only the counts of its own pushes, nothing else.

3. In “Reach” choose “This company”, “Every company in the group” (only an account owner or administrator) or “Every client of the prevention service” (only a service administrator).

4. If the key should reach only some data, open “Per-resource scopes (public API)” and tick read or write for each resource. “Read” and “Write” do not cover medical aptitude or the audit trail: each needs its own scope.

5. Press “Create a key”. “Copy this key now — it will not be shown again:” appears. Copy it, store it in the system that will use it and press “Done”.

3. Rotate, revoke and watch usage

Each key in the list shows its name, its scopes, its reach when it is not the company, and its “last used” date. “Rotate” generates a new value for the same key (the old one stops working) and shows it once. “Revoke” opens the “Revoke API key” confirmation: once accepted, the key stops working immediately and this cannot be undone. Use it when a system no longer needs the key or if you suspect it has leaked.

A revoked or expired key is marked “revoked” or “expired” and has no buttons. API usage against your plan quota is shown in “Integration monitoring”.

“Provider ingests” lists what each provider key has pushed: the provider (the key name), the type (appointments, outcomes, certificates, screening results, FHIR, audiometer or spirometer CSV), the “Accepted”, “Repeated” and “Rejected” counts and the date received. It shows counts only, never clinical data.

4. One key per system

Create a separate key for each system that connects: if one is retired or compromised you revoke only its key, the others keep working, and “last used” tells you which is active. The “Expiring in 30 days” card flags the keys to renew in good time.

The key gives access to the company's data with the scopes you chose: keep it in the secrets manager of the system that uses it, never in an e-mail or a spreadsheet.