API keys and webhooks
Connect your own tools (ERP, accounting, Power Automate…): keys to read or write your data, webhooks to be told about each event. Owners and administrators only.
Creating and managing a key
“New key”: a name (the tool that uses it), its accesses, its validity. A key that writes or exports expires within a year at most. The key is shown only once: copy it; if lost, revoke it and create another. The full export is for owners only, with your password, and the other owners are notified. A key that manages members invites in your name, only managers and viewers, and stops if you are no longer an owner or administrator. A key that approves and rejects documents decides in your name, within your scope, counts as you when a second approval is required, never on health data, and stops once you can no longer review documents. The list shows the accesses, last use, expiry, “No end date: replace it” and “Creator no longer has access” (its creator left or no longer manages keys: it still works, except to manage members, and to approve or reject when its creator can no longer review documents; replace it with a key you create). “Revoke” cuts the key at once.
Fields and buttons
- New key
- One key per tool: revoking one tool's key does not stop the others. At most 20 active keys per organization.
- Name
- The tool that uses it; this name appears in the audit log for each action of the key.
- Permissions
- What the key may read or do: tick only what the tool needs. “Export all data and documents” asks for your password.
- Validity
- A key that writes or exports expires within a year at most; a key that only reads may stay “No expiry”.
- Copy the key
- The key is shown only once: paste it into your tool before closing. Lost, revoke it and create another one.
- Last used
- Day of the last call made with this key; “Never”: the key has never been used.
- Expires
- After this date, the tool's calls are refused. A notice warns you 14 days before: create the next key and put it in the tool.
- No end date: replace it
- A key without an end date that writes or exports, created before the one-year limit: replace it with a dated key, then revoke it.
- Expires soon
- Less than 14 days before the end date; a notice and an email tell you. Replace the key before that date.
- Creator no longer has access
- Its creator left or no longer manages keys. It still works, except to manage members: replace it with a key you create, then revoke it. A key that approves documents also stops once they can no longer review them.
- Revoke
- Stops the key at once, for good; the webhooks it subscribed are paused.
Allowed addresses and test
“IP addresses” limits a key to your servers' addresses: one address or range per line, IPv4 or IPv6; empty, every address. A call from another address is refused. “Test a key” checks a key from your browser (sent to the API, never stored) and says whether the address is refused. Each action of a key is written to the audit log with its IP address, erased after 12 months.
Fields and buttons
- Limit to some IP addresses
- In “New key”: the IP addresses of your servers, set at creation. One address or range per line, IPv4 or IPv6.
- IP addresses
- Changes the allowed addresses of an existing key; empty: any address. A call from another address is refused and written to the audit log.
- Test a key
- Checks from your browser that a key is accepted, without keeping it; reports a key refused for the address of the call.
- Calendar address
- With the “Read the calendar of deadlines” permission: the address to paste into Google Calendar, Outlook or Apple Calendar. It contains the key: do not share it.
Webhooks
“Add an endpoint”: your tool's address, a name and the events you want (requirement created or status changed, document received or reviewed, finding, third-party compliance…). Vigilo sends a signed request there at each event; the details are read through the API. The signing secret is shown only once. “Renew the signing secret” creates a new one; the previous one stays valid for 24 h (each send then carries both signatures), unless you untick the box because it leaked. “Test” sends a test event, “History” shows the latest sends and their state; an endpoint can be paused or deleted. The “Developer guide” gives examples to copy and the OpenAPI specification.
Fields and buttons
- Add an endpoint
- An address of your tool that will receive the events; at most 25 endpoints per organization, including those subscribed by an API key.
- Address
- A public https address: a private address is refused and redirects are not followed. Your tool must answer within 10 seconds.
- Events
- Those that trigger a delivery. “Requirement created” is unticked by default: an assignment rule creates hundreds at once.
- Test
- Sends a “Test” event to check the address and the signature; the result shows in “History”.
- History
- The last 50 deliveries, with your tool's answer and the duration. A failed delivery is retried 8 times over about 24 hours; “Replay” sends it again.
- Renew the signing secret
- Creates a new signing secret, shown once. The old one still signs for 24 hours, unless you untick the box because it was disclosed.
- Remove the previous secret now
- Removes the old secret before the 24 hours are over, once your tool uses the new one.
- Pause
- No more deliveries until “Resume”. Vigilo pauses on its own an endpoint whose last 5 deliveries failed, and tells you.
- Resume
- Restarts deliveries for the next events; those that happened during the pause are not sent. Not possible if the API key that subscribed it is revoked or expired.
- Delete
- Deletes the endpoint and its delivery history. To stop for a while, use “Pause” instead.
SFTP access
“Create an access”: a name (the tool or partner that uses it), an SSH public key (recommended for an automated tool) or a generated password, shown only once, an expiry and, if needed, the allowed IP addresses; your password confirms the creation. The access reads, read only, every approved document of the organization, filed as in “Documents”: type of document, then third party, site, unit or equipment, then the files preceded by their date. Health data is never there. At the first connection, compare the fingerprint your client shows with the one on the page. Each connection and each file read is in the audit log. After 10 wrong attempts, the login and the address are blocked for 15 minutes. “Revoke” cuts the access at once. 10 active accesses at most.