Public REST API

1. Autentisering

Alla anrop mot /api/v1/* kräver en API-nyckel av formatet ck_live_<åtta tecken>_<hex-secret>. Nyckeln skickas som Authorization: Bearer <nyckel>. Cookies från ett inloggat dashboard-konto avvisas explicit; nyckeln är den enda accepterade autentiseringen mot v1.

Skapa nycklar i dashboarden under Inställningar / API-nycklar. Endast administratörer kan skapa eller återkalla nycklar. Plaintext visas en gång vid skapande och kan inte återhämtas, så förvara värdet i ett hemlighetshanteringssystem. CyberKlar lagrar enbart en SHA-256-hash av nyckeln. En återkallad nyckel ger 401 omedelbart; raden ligger kvar i databasen så att audit-loggen behålls intakt.

2. Scope-modell

Varje nyckel har en explicit lista med scopes. Endpointet kontrollerar det scope som krävs för operationen och svarar med 403 om scopet saknas. Använd separata nycklar per system och undvik bredare rättigheter än nödvändigt.

3. Rate-limit

Varje nyckel får göra 600 requests per minut. Vid överskridande returneras 429 med headern Retry-After i sekunder, samt X-RateLimit-Limit, X-RateLimit-Remaining och X-RateLimit-Reset (millisekund-epoch när fönstret nollställs). Större kvoter kan avtalas separat för on-prem-integrationer mot SIEM, ITSM eller HR-system.

4. Felhantering

Alla fel följer samma struktur: { "error": { "code", "message", "details? } }. Statuskoder och codes:

Varje svar innehåller X-Request-Id. Inkludera den vid supportärenden så hittar vi requesten i audit-loggen.

5. Endpoints

Bas-URL: https://cyberklar.se. Alla endpoints loggas i en append-only audit-tabell med organisations-id, key-prefix, metod, route, status, latens och request-id.

curl -X POST https://cyberklar.se/api/v1/incidents \
  -H "Authorization: Bearer ck_live_abcd1234_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Ransomware mot filserver",
    "description": "Kryptering upptäckt i SMB-share kl 03:14.",
    "severity": "critical",
    "affected_systems": ["fs-prod-01", "epost"],
    "affected_persons_count": 150,
    "detected_at": "2026-05-08T03:14:00Z",
    "regulation": "nis2"
  }'

{
  "id": "8b1...",
  "organization_id": "...",
  "title": "Ransomware mot filserver",
  "severity": "critical",
  "is_significant": true,
  "early_warning_deadline": "2026-05-09T03:14:00Z",
  "notification_deadline": "2026-05-11T03:14:00Z",
  "final_report_deadline": "2026-06-11T03:14:00Z",
  "status": "open",
  "regulation": "nis2"
}

curl https://cyberklar.se/api/v1/incidents?limit=50 \
  -H "Authorization: Bearer ck_live_abcd1234_..."

{
  "data": [
    { "id": "...", "title": "...", "severity": "high", ... }
  ],
  "next_cursor": null
}

curl https://cyberklar.se/api/v1/incidents/8b1... \
  -H "Authorization: Bearer ck_live_abcd1234_..."

{
  "id": "8b1...",
  "title": "Ransomware mot filserver",
  "status": "open",
  ...
}

curl -X POST https://cyberklar.se/api/v1/assets \
  -H "Authorization: Bearer ck_live_abcd1234_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order-databas prod",
    "asset_type": "database",
    "classification": "confidential",
    "business_criticality": "high",
    "hosted_in_eu": true,
    "contains_personal_data": true
  }'

{
  "id": "a91...",
  "name": "Order-databas prod",
  "asset_type": "database",
  "classification": "confidential",
  "business_criticality": "high",
  "status": "active"
}

curl https://cyberklar.se/api/v1/assets?limit=100 \
  -H "Authorization: Bearer ck_live_abcd1234_..."

{
  "data": [
    { "id": "...", "name": "...", "asset_type": "system", ... }
  ],
  "next_cursor": null
}

curl -X POST https://cyberklar.se/api/v1/suppliers \
  -H "Authorization: Bearer ck_live_abcd1234_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hosting AB",
    "org_number": "5560000000",
    "category": "critical",
    "service_description": "Drift av produktionsmiljö i EU.",
    "contact_email": "kontakt@hosting.se"
  }'

{
  "id": "c42...",
  "name": "Hosting AB",
  "category": "critical",
  "service_description": "Drift av produktionsmiljö i EU.",
  "risk_score": 0,
  "assessment_status": "pending"
}

curl https://cyberklar.se/api/v1/suppliers \
  -H "Authorization: Bearer ck_live_abcd1234_..."

{
  "data": [
    { "id": "...", "name": "...", "category": "critical", ... }
  ],
  "next_cursor": null
}

6. Maskinläsbar spec

OpenAPI 3.1-spec genereras dynamiskt och kan importeras i Postman, Insomnia eller en kodgenerator:

/api/v1/openapi.json

Specen innehåller säkerhetsschemat bearerAuth, alla sju endpoints, request- och response-schemas, samt felkoder per endpoint. Den hålls synkroniserad med Zod-schemana som driver valideringen i runtime.

7. Versionering och deprecering

Den nuvarande versionen är v1. Bakåtbrytande ändringar kommer att introduceras under /api/v2/*. Ej bakåtbrytande tillägg (nya fält i svar, nya valfria request-fält) görs löpande på v1. Vi kommunicerar deprecering minst sex månader i förväg via mejl till kontoadministratörer och i svaren via headern Sunset enligt RFC 8594.

8. Support

Frågor om API:et besvaras via support@cyberklar.se. Inkludera X-Request-Id från det aktuella svaret om det rör en specifik request.