API Documentation

Verify Swedish BankID delegations programmatically. Sandbox out of the box, production via BankID-signed onboarding.

Quick start

Sandbox keys (prefix mk_test_) work immediately and never charge quota. Live keys (mk_live_) issue after BankID-signed onboarding.

Get sandbox key

Authentication

Send your key id and secret as request headers. The middleware splits sandbox from production traffic by prefix and rejects keys outside the org IP allowlist (when set).

http

GET /api/external/delegations HTTP/1.1
Host: api.minionapp.se
X-Api-Key: mk_live_a1b2c3d4e5
X-Api-Secret: <your secret>

Endpoints

Two read endpoints in V1. Mutating endpoints (create / accept / revoke) are end-user surfaces and require BankID, not API keys.

GET/api/external/delegations

List delegations granted to your organization. Filter by status (Active, Accepted, Revoked, Expired).

status	string?	Filter (default: Active)
page	int	Default 1
pageSize	int	Default 50, max 200

GET/api/external/delegations/{verificationCode}

Look up a single delegation by its 8-character verification code. Useful for verifying that a delegation a user shared is genuinely active in your org.

verificationCode

string

Path param, e.g. AB3K7XYZ

Webhooks

Set a callback URL in Settings; we POST signed JSON on delegation events. Each request carries an HMAC-SHA256 signature in the X-Minion-Signature header. Verify it with the per-org secret you got at first save.

http

POST /webhooks/minion HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Minion-Signature: sha256=4f3c...e2a1
X-Minion-Event: delegation.accepted
X-Minion-Delivery: 8d2c-...

{
  "event": "delegation.accepted",
  "delegationId": "9f8a7b6c-...",
  "verificationCode": "AB3K7XYZ",
  "occurredAt": "2026-05-02T11:30:00Z"
}

expectedSig = HMAC_SHA256(secret, rawBody) — compare with constant-time equality.

Failed deliveries (non-2xx, timeout, or unreachable host) retry up to 5 times with exponential backoff: 1s, 5s, 30s, 5m, 30m.

Rate limits & quota

Per-key rate limit comes from your plan. Each successful production call deducts one from the org owner's monthly quota. Sandbox calls do not consume quota and are capped at 1 000 req/day.

Free — 100 req/min, 1 000 req/mo
Starter — 600 req/min, 10 000 req/mo
Business — 1 800 req/min, 50 000 req/mo
Enterprise — custom

Examples

Same flow in three languages.

curl

curl -H "X-Api-Key: mk_test_a1b2c3" \
     -H "X-Api-Secret: ${MINION_SECRET}" \
     https://api.minionapp.se/api/external/delegations?status=Active

javascript

const res = await fetch('https://api.minionapp.se/api/external/delegations?status=Active', {
  headers: {
    'X-Api-Key': 'mk_test_a1b2c3',
    'X-Api-Secret': process.env.MINION_SECRET,
  },
});
const { items } = await res.json();

python

import os, requests

r = requests.get(
    'https://api.minionapp.se/api/external/delegations',
    params={'status': 'Active'},
    headers={
        'X-Api-Key': 'mk_test_a1b2c3',
        'X-Api-Secret': os.environ['MINION_SECRET'],
    },
)
items = r.json()['items']