Integration Details

API Keys

Scoped, expiring, revocable credentials for the data feeds — stored hashed, shown once.

Talk to us

Overview

API keys are how machine clients — Power BI, Excel, a script, a scheduled job — authenticate to Monival’s data feeds without using a person’s login.

They are not a convenience wrapper around a user account. A key is its own credential, with its own scope, its own permissions and its own expiry, and revoking it affects nothing else.

How a key is scoped

Every key carries three boundaries:

Organisation. A key belongs to one organisation and cannot reach another’s data. This is enforced on every query, not only at issue.

Project. A key is created against a specific project, so a key issued for one programme’s data collection does not become a general credential for everything the organisation holds.

Permissions. A key carries an explicit permission list. Keys default to read-only (data.read) unless write access is requested at creation. Issue read-only unless the client genuinely needs to write — a Power BI dataset never does.

Expiry and revocation

Expiry is optional but recommended. Set an expiry date at creation and the key stops working after it, whether or not anyone remembers it exists. A key with no expiry is a credential that outlives the project, the laptop and often the employee.

Revocation is immediate. Revoking a key deletes it; the next request using it fails. There is no grace period and nothing to wait for, which is what you want when a laptop goes missing.

How keys are stored

  • The key is generated as a cryptographically random 32-byte value, rendered as a monival_-prefixed string.
  • It is hashed with bcrypt before storage. The raw key is never written to the database.
  • You see the raw key once, at creation. Monival cannot show it to you again, because Monival does not have it. If it is lost, revoke it and issue a new one — that is the correct response, not an inconvenience.
  • Key listings exclude the hash entirely, so the stored credential material is not returned even to an authorised administrator.
  • Each key records a last-used timestamp, which is how you find the keys nobody is using any more.

Managing them well

A short discipline that prevents most credential problems:

  1. One key per consumer. One for the Power BI dataset, one for the finance team’s Excel workbook, one per script. Shared keys cannot be revoked without breaking something you did not intend.
  2. Name them for the consumer, not for the person who created them. “Quarterly donor dashboard — Power BI” tells the next administrator what breaks if they revoke it. “Amina’s key” does not.
  3. Always set an expiry, and put the rotation date in a shared calendar.
  4. Read-only by default.
  5. Review last-used dates periodically and revoke anything dormant.
  6. Never put a key in a shared spreadsheet, a chat message or a committed file. Use your organisation’s secret store; if you do not have one, the key belongs in a password manager entry owned by a team, not a person.
  7. Revoke on staff departure — not as a precaution, as a routine step in the offboarding checklist.