Authentication and API keys

Every API request carries an API key in the x-api-key header. A key acts as the user it belongs to: the same role, outlets and permissions, checked again on every request.

Recommended: create an API user

Instead of a key on a person’s account, create a dedicated API user for the integration. An API user can’t sign in, starts with no permissions at all, and you give it only what the integration needs.

1. Sign in as the organization owner.
2. Open Settings → API Keys and choose Create API User.
3. Open that API user’s member page and grant the permissions the integration needs (for example read-only products and stock), plus the outlets it may access.
4. Go back to Settings → API Keys and generate a key for the API user.

Creating a key

• Expiry is required: 1–365 days (default 90). Expired keys are refused. Owners get reminders before a key expires.
• IP allowlist (optional): IPv4/IPv6 addresses or CIDRs, one per line. Empty means any IP. Use it for server-to-server integrations with fixed IPs.
• Shown once. Copy the key right after it’s generated. Medivy stores only its hash, so a lost key can’t be shown again: revoke it and create a new one.

Caution

Treat an API key like a password: keep it in a secret manager or a server environment variable, never in source code or in client-side apps (browsers, mobile apps).

Using the key

curl -H "x-api-key: mdv_…" https://api.medivy.id/api/dash/<orgId>/products

<orgId> is your organization ID. For per-outlet endpoints (/outlets/<outletId>/…), the key’s user must be assigned to that outlet.

Disabling and revoking

In Settings → API Keys you can disable, re-enable or revoke a key. Changes apply from the next request. Every action is written to the audit log, and each key shows when and from which IP it was last used.