Appearance
API Keys
API keys let external systems call the Medipal API without an interactive sign-in. They are managed under Admin Panel → Access → API Keys.
How a key behaves
- A key acts on behalf of the user who created it: everything done with the key is attributed to that user.
- A key carries a subset of the creator's scopes, chosen at creation. It can never do more than its creator can; if the creator loses a role later, the key loses those rights too.
- A key has an expiry and can be revoked at any time.
- The key value is shown once, at creation. Afterwards only a short hint of it is visible.
Creating a key
- Choose Create API Key.
- Enter a name and description that identify the integration (for example "Data warehouse export").
- Choose the expiry period.
- Select the scopes in the matrix. Grant only what the integration needs; read-only integrations need read scopes only.
- Confirm, then copy the key from the reveal dialog and store it in the integration's secret store. Close the dialog; the value cannot be displayed again.
The key list
| Column | Meaning |
|---|---|
| Name | The label given at creation. |
| Token | The last characters of the key, to recognise it. |
| Scopes | The scopes granted. |
| Expires | Expiry date. |
| Last used | When the key last authenticated a request. |
| Status | Active, Expired or Revoked. |
Revoke Token disables a key immediately. There is no way to re-enable a revoked key; create a new one.
Rotation
To rotate a key without downtime: create the new key with the same scopes, switch the integration to it, verify with the Last used column, then revoke the old key.
Where keys are used
| Use | Notes |
|---|---|
| Third-party integrations | Reading submissions, creating patients or enrollments, exporting data. See API Access. |
| Server plugins that read platform data | A plugin instance can be given a key stored in the Vault; the platform enforces the key's scopes on every call the plugin makes. See Plugins. |
| Custom clients | Any client that speaks HTTPS and can hold a secret. |
Keys are for system-to-system use. People should sign in with their own account so that actions are attributed correctly.
Permissions
Creating, listing and revoking API keys requires authentication-management rights, which only administrators hold by default. An integration role cannot create keys for itself; an administrator creates the key and hands it over.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| Requests are rejected as unauthorised | Wrong header, expired or revoked key | Check the status column; see API Access for the request format. |
| Requests are forbidden for one endpoint | The key lacks the scope that endpoint requires | Create a new key with the missing scope. |
| The key stopped working after a role change | The creator lost a role the key depended on | Recreate the key from an account that holds the rights. |
| "Create API Key" is missing | Missing authentication-management rights | Ask an administrator. |