1. Autentisering

Alla anrop mot /api/v1/* kräver en API-nyckel. Den skickas som Authorization: Bearer <nyckel>. Cookies från ett inloggat plattformskonto avvisas; nyckeln är den enda accepterade autentiseringen mot v1. Lägg nyckeln i er hemlighetshantering och läs den som miljövariabel, som i exemplen nedan. Skriv aldrig in den i ett skript eller i en pipeline-fil.

Skapa nycklar i plattformen 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. Behörighetsmodell

Varje nyckel får en uttrycklig lista med behörigheter, satta när nyckeln skapas. Behörigheten prövas vid varje anrop och saknad behörighet besvaras med 403. Använd separata nycklar per system och ge aldrig en nyckel bredare rättigheter än den behöver: en nyckel som bara ska rapportera utvärderingsresultat ska inte kunna läsa incidentregistret.

Område	Läsa	Skriva
Incidenter	Lista och hämta incidenter	Skapa incidenter
Tillgångar	Lista tillgångar	Skapa tillgångar
Leverantörer	Lista leverantörer	Skapa leverantörer
AI-utvärderingar	Lista utvärderingar och utvärderingssviter	Skicka in utvärderingsresultat
AI-agentkörningar	Lista inskickade körningar	Skicka in körningar och händelser (passiv telemetri)
Utvärderingsgrinden	Fråga gate-status. Varje fråga skriver ett beslut.	Ingen skrivbehörighet

Behörigheterna väljs per nyckel under Inställningar / API-nycklar. De exakta identifierarna som skickas i specen finns i /api/v1/openapi.json, som genereras ur det som faktiskt körs och därför aldrig kan hamna ur fas med den här sidan.

3. Anropstak

Anropstakten är begränsad per nyckel. Gällande gräns, återstående kvot och tidpunkt då fönstret nollställs returneras i varje svar via X-RateLimit-Limit, X-RateLimit-Remaining och X-RateLimit-Reset. Läs dem i stället för att gissa, så påverkas er integration inte om taket ändras. Vid överskridande returneras 429 med Retry-After i sekunder. Högre tak kan avtalas separat för integrationer mot SIEM, ITSM eller HR-system.

4. Felhantering

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

Status	Code	Innebörd
400	`validation_error`	Saknade eller ogiltiga fält. `details` innehåller en flatten av Zod-felet.
401	`unauthorized`	Nyckeln saknas, är okänd, har återkallats eller cookies har skickats.
403	`forbidden`	Nyckeln saknar det scope som endpoint kräver.
404	`not_found`	Resursen finns inte i nyckelns organisation.
415	`unsupported_media_type`	Content-Type måste vara `application/json`.
429	`rate_limited`	Rate-limit nådd. Läs `Retry-After`.
500	`internal_error`	Internt fel. Korrelations-id finns i headern `X-Request-Id`.

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. Varje anrop registreras i en append-only revisionslogg: vilken nyckel som användes, vilken operation det gällde, utfall och tidpunkt. Raderna kan inte ändras eller raderas i efterhand, så loggen håller vid en tillsynsbegäran.

POST/api/v1/incidentsKräver: Skriva incidenter

Skapa incident

Skapar en ny incident i organisationen. Plattformen beräknar automatiskt deadlines för upplysning (24 h), incidentanmälan (72 h) och slutrapport (1 månad), samt sätter is_significant utifrån severity.

Exempelanrop

curl -X POST https://cyberklar.se/api/v1/incidents \
  -H "Authorization: Bearer $CYBERKLAR_API_KEY" \
  -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"
  }'

Exempelsvar

{
  "id": "8b1...",
  "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"
}

GET/api/v1/incidentsKräver: Läsa incidenter

Lista incidenter

Returnerar incidenter för organisationen sorterade efter created_at fallande. Använd limit (1 till 200, default 50) och cursor (UUID från next_cursor i föregående svar) för keyset-paginering.

Exempelanrop

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

Exempelsvar

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

GET/api/v1/incidents/{id}Kräver: Läsa incidenter

Hämta incident

Hämtar en specifik incident utifrån UUID. Returnerar 404 om incidenten inte tillhör nyckelns organisation, även om id:t finns hos en annan organisation.

Exempelanrop

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

Exempelsvar

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

POST/api/v1/assetsKräver: Skriva tillgångar

Skapa tillgång

Lägger till en tillgång i AI- och informationsregistret. Klassning (public, internal, confidential, restricted) och affärskritikalitet styr senare riskbedömningar.

Exempelanrop

curl -X POST https://cyberklar.se/api/v1/assets \
  -H "Authorization: Bearer $CYBERKLAR_API_KEY" \
  -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
  }'

Exempelsvar

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

GET/api/v1/assetsKräver: Läsa tillgångar

Lista tillgångar

Returnerar tillgångar för organisationen sorterade efter created_at fallande. Stödjer keyset-paginering på samma sätt som incidents.

Exempelanrop

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

Exempelsvar

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

POST/api/v1/suppliersKräver: Skriva leverantörer

Skapa leverantör

Registrerar en leverantör i leverantörsregistret. Kategori (critical, important, standard) styr vilken bedömningsprocess plattformen kräver.

Exempelanrop

curl -X POST https://cyberklar.se/api/v1/suppliers \
  -H "Authorization: Bearer $CYBERKLAR_API_KEY" \
  -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"
  }'

Exempelsvar

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

GET/api/v1/suppliersKräver: Läsa leverantörer

Lista leverantörer

Returnerar leverantörer för organisationen. Använd limit och cursor för paginering precis som för andra endpoints.

Exempelanrop

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

Exempelsvar

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

POST/api/v1/ai-evaluationsKräver: Skriva AI-utvärderingar

Ta emot AI-utvärderingsresultat

Adapter för externa eval-verktyg (Azure AI Evaluation, Vertex AI, LangSmith, Arize m.fl.). Resultaten lagras append-only som bevis och SHA-256-hashas. AI-systemet matchas på ai_system_id eller ai_system_name. Valfritt fält eval_suite (svitens namn eller id) knyter resultatet till en utvärderingssvit: namn matchar aktuell svitversion, och bara resultat mot aktuell version räknas i svitens utfall. Body får vara ett objekt, en array eller { evaluations: [...] } (batch, max 100). CyberKlar kör ingen egen utvärdering; mätningen sker i era verktyg.

Exempelanrop

curl -X POST https://cyberklar.se/api/v1/ai-evaluations \
  -H "Authorization: Bearer $CYBERKLAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_system_name": "Kundtjänst-copilot",
    "source": "azure-ai-eval run 4821",
    "source_kind": "azure_ai",
    "eval_type": "prompt_injection",
    "metric_name": "attack_success_rate",
    "metric_value": 0.02,
    "threshold": 0.05,
    "passed": true,
    "evaluated_at": "2026-07-18T09:00:00Z",
    "payload": { "runId": "4821", "cases": 500 },
    "eval_suite": "Kundtjänst-copilot release-krav"
  }'

Exempelsvar

{
  "created": 1,
  "data": [
    {
      "id": "e91...",
      "ai_system_id": "a12...",
      "eval_type": "prompt_injection",
      "metric_name": "attack_success_rate",
      "passed": true,
      "evaluated_at": "2026-07-18T09:00:00Z",
      "payload_hash": "9f2c...",
      "eval_suite_id": "s31...",
      "eval_suite_version": 2
    }
  ]
}

GET/api/v1/ai-evaluationsKräver: Läsa AI-utvärderingar

Lista AI-utvärderingar

Returnerar inskickade utvärderingsresultat för organisationen. Filtrera med ai_system_id och eval_type. Keyset-paginering via limit och cursor precis som övriga endpoints.

Exempelanrop

curl "https://cyberklar.se/api/v1/ai-evaluations?eval_type=drift&limit=50" \
  -H "Authorization: Bearer $CYBERKLAR_API_KEY"

Exempelsvar

{
  "data": [
    { "id": "...", "ai_system_id": "...", "eval_type": "drift", "passed": true, ... }
  ],
  "next_cursor": null
}

GET/api/v1/eval-suitesKräver: Läsa AI-utvärderingar

Lista utvärderingssviter

Returnerar organisationens utvärderingssviter (alla versioner): namngivna, versionerade kravsviter med numeriska trösklar per AI-system. Läs sviten i ert CI-flöde innan resultat rapporteras via POST /api/v1/ai-evaluations med fältet eval_suite. Filtrera med ai_system_id och status (active = aktuell version). Sviter skapas och versioneras i plattformen, aldrig via API:t.

Exempelanrop

curl "https://cyberklar.se/api/v1/eval-suites?status=active&limit=50" \
  -H "Authorization: Bearer $CYBERKLAR_API_KEY"

Exempelsvar

{
  "data": [
    {
      "id": "s31...",
      "ai_system_id": "a12...",
      "name": "Kundtjänst-copilot release-krav",
      "version": 2,
      "status": "active",
      "thresholds": [
        { "metric_name": "attack_success_rate", "eval_type": "prompt_injection", "operator": "lte", "value": 0.05 }
      ],
      "superseded_by": null
    }
  ],
  "next_cursor": null
}

GET/api/v1/gate-status/{aiSystemId}Kräver: Fråga utvärderingsgrinden

Fråga utvärderingsgrinden

Utvärderingsgrinden (release gate) svarar pass eller block med maskinläsbara skäl: pass kräver en godkänd körning av aktuell svitversion, ingen öppen driftavvikelse och att agentens modell-/promptversion matchar senast certifierad version. Varje anrop skriver ett gate-beslut som aldrig kan ändras i efterhand, med indata-snapshot och SHA-256-hash: frågan är själva bevishändelsen. CyberKlar svarar; er pipeline fattar beslutet och plattformen kör, stoppar eller blockerar aldrig agenten. Kräver tillägget Agentstyrning.

Exempelanrop

curl https://cyberklar.se/api/v1/gate-status/a12... \
  -H "Authorization: Bearer $CYBERKLAR_API_KEY"

Exempelsvar

{
  "decision": "block",
  "reasons": ["no_approved_run"],
  "reason_details": [
    { "code": "no_approved_run", "message": "Ingen godkänd körning av aktuell svitversion." }
  ],
  "certification_id": null,
  "decision_id": "g77...",
  "ai_system_id": "a12...",
  "eval_suite_id": "s31...",
  "eval_suite_version": 2,
  "payload_hash": "4c1d...",
  "decided_at": "2026-07-23T10:00:00Z"
}

POST/api/v1/agent-runsKräver: Rapportera AI-agentkörningar

Ta emot AI-agentkörningar

Passiv runtime-telemetri för AI-agenter (register, inte enforcement). Körningen kopplas till en agentprofil via agent_identity; saknas profilen loggas körningen ändå och ett luckförslag skapas. Body får vara ett objekt, en array eller { runs: [...] } (batch, max 100). Append-only. run_ref är er egen körnings-referens och måste vara unik per organisation. CyberKlar tar emot loggen men kör, stoppar eller blockerar aldrig agenten.

Exempelanrop

curl -X POST https://cyberklar.se/api/v1/agent-runs \
  -H "Authorization: Bearer $CYBERKLAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_identity": "svc-kundtjanst-copilot",
    "run_ref": "run-4821",
    "model_name": "gpt-4o",
    "model_version": "2026-05",
    "started_at": "2026-07-20T09:00:00Z",
    "status": "completed"
  }'

Exempelsvar

{
  "created": 1,
  "data": [
    {
      "id": "r91...",
      "ai_agent_profile_id": "p12...",
      "agent_identity": "svc-kundtjanst-copilot",
      "run_ref": "run-4821",
      "status": "completed",
      "started_at": "2026-07-20T09:00:00Z"
    }
  ]
}

POST/api/v1/agent-runs/{runId}/eventsKräver: Rapportera AI-agentkörningar

Ta emot händelser i en körning

Händelser i en tidigare inskickad körning: tool_call, proposed_action, executed_action, approval, rejection. seq är ert sekvensnummer (unikt per körning). Ett verktyg (tool_name) utanför agentprofilens dokumenterade tools-lista driver ett tool_drift-förslag och en omprövningstrigger. Body får vara ett objekt, en array eller { events: [...] } (batch, max 500). Append-only.

Exempelanrop

curl -X POST https://cyberklar.se/api/v1/agent-runs/r91.../events \
  -H "Authorization: Bearer $CYBERKLAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seq": 0,
    "event_type": "tool_call",
    "tool_name": "web_search",
    "occurred_at": "2026-07-20T09:00:05Z",
    "payload": { "query": "..." }
  }'

Exempelsvar

{
  "created": 1,
  "data": [
    { "id": "e01...", "seq": 0, "event_type": "tool_call", "tool_name": "web_search", "payload_hash": "1a2b..." }
  ]
}

GET/api/v1/agent-runsKräver: Rapportera AI-agentkörningar

Lista AI-agentkörningar

Returnerar inskickade körningar för organisationen. Filtrera med ai_agent_profile_id. Keyset-paginering via limit och cursor precis som övriga endpoints.

Exempelanrop

curl "https://cyberklar.se/api/v1/agent-runs?limit=50" \
  -H "Authorization: Bearer $CYBERKLAR_API_KEY"

Exempelsvar

{
  "data": [
    { "id": "r91...", "agent_identity": "svc-kundtjanst-copilot", "run_ref": "run-4821", "status": "completed", ... }
  ],
  "next_cursor": null
}

6. CI/CD-integration: utvärderingsgrinden

Utvärderingsgrinden gör "No Evals, No Production" till ett maskinellt prövbart steg i er pipeline. Flödet är tre steg: rapportera utvärderingsresultat, fråga gate-status, och avbryt pipelinen vid block. Beslutet fattas av er pipeline enligt er konfiguration: CyberKlar svarar med beslut och skäl, och kör, stoppar eller blockerar aldrig era agenter. Varje fråga förseglas som ett beslut som aldrig kan ändras i efterhand, med låst indata-snapshot, så att hela beslutshistoriken finns kvar som underlag vid granskning.

Referensexempel för GitHub Actions (stegen körs efter er egen utvärdering, t.ex. Promptfoo eller Azure AI Evaluation):

# .github/workflows/agent-release.yml (utdrag)
- name: Rapportera utvärderingsresultat
  run: |
    curl -sf -X POST https://cyberklar.se/api/v1/ai-evaluations \
      -H "Authorization: Bearer ${{ secrets.CYBERKLAR_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d @eval-results.json

- name: Fråga utvärderingsgrinden
  run: |
    DECISION=$(curl -sf https://cyberklar.se/api/v1/gate-status/${{ vars.AI_SYSTEM_ID }} \
      -H "Authorization: Bearer ${{ secrets.CYBERKLAR_API_KEY }}" \
      | jq -r '.decision')
    echo "Gate-beslut: $DECISION"
    # Er pipeline fattar beslutet: avbryt vid block.
    if [ "$DECISION" != "pass" ]; then
      echo "Utvärderingsgrinden svarade block - avbryter driftsättningen."
      exit 1
    fi

Motsvarande i GitLab CI:

# .gitlab-ci.yml (utdrag)
gate-check:
  stage: deploy-gate
  script:
    - |
      curl -sf -X POST https://cyberklar.se/api/v1/ai-evaluations \
        -H "Authorization: Bearer $CYBERKLAR_API_KEY" \
        -H "Content-Type: application/json" \
        -d @eval-results.json
    - |
      DECISION=$(curl -sf https://cyberklar.se/api/v1/gate-status/$AI_SYSTEM_ID \
        -H "Authorization: Bearer $CYBERKLAR_API_KEY" | jq -r '.decision')
      echo "Gate-beslut: $DECISION"
      # Er pipeline fattar beslutet: avbryt vid block.
      if [ "$DECISION" != "pass" ]; then exit 1; fi

Skälkoderna i reasons är stabila och maskinläsbara: no_approved_run (ingen godkänd körning av aktuell svitversion), suite_version_changed (sviten har ändrats sedan certifieringen), version_drift (modell-/promptversionen avviker från senast certifierad version), open_drift_trigger (öppen driftavvikelse), suite_missing, agent_profile_missing samt attestation_missing (en eller flera av de konfigurerade rollerna har inte attesterat aktuell svit- och agentversion; svaret listar rollerna i missing_attestation_roles). Attester registreras av behöriga användare i plattformen på systemets detaljsida, aldrig via API: de är den mänskliga länken i ansvarskedjan.

7. 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 endpoints, request- och response-schemas, samt felkoder per endpoint. Den hålls synkroniserad med Zod-schemana som driver valideringen i runtime.

8. Verifiera exporterade bevispaket

Bevispaketen från CyberKlar Control (GET /api/control/evidence-export, kräver Control-modulen och inloggad session) och incidenternas underlagspaket i zip-format är signerade med en asymmetrisk nyckel i Google Cloud KMS (EC P-256). De verifieras offline, utan CyberKlar, med det öppna verifieringsverktyget:

/verifiering/verify-evidence-package.mjs (ren Node.js 20+, inga beroenden; samma fil följer med i varje paket)

node verify-evidence-package.mjs bevispaket.zip

Publicerad verifieringsnyckel: /.well-known/cyberklar-signing-key.pem. Paketets VERIFIERING.md beskriver även verifiering med openssl steg för steg.

9. 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.

10. Angränsande dokumentation

Ska ert system skicka in incidenter i stället för att anropa API:et beskrivs den vägen i webhook-dokumentationen. Där behöver det sändande systemet ingen API-nyckel, bara en signerad POST. Övriga utvecklarytor är samlade på dokumentationens startsida.

Hur plattformen är byggd, var datan ligger och vilka underbiträden som anlitas står på förtroendesidan.

11. 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.

Public REST API

1. Autentisering

2. Behörighetsmodell

3. Anropstak

4. Felhantering

5. Endpoints

Skapa incident

Exempelanrop

Exempelsvar

Lista incidenter

Exempelanrop

Exempelsvar

Hämta incident

Exempelanrop

Exempelsvar

Skapa tillgång

Exempelanrop

Exempelsvar

Lista tillgångar

Exempelanrop

Exempelsvar

Skapa leverantör

Exempelanrop

Exempelsvar

Lista leverantörer

Exempelanrop

Exempelsvar

Ta emot AI-utvärderingsresultat

Exempelanrop

Exempelsvar

Lista AI-utvärderingar

Exempelanrop

Exempelsvar

Lista utvärderingssviter

Exempelanrop

Exempelsvar

Fråga utvärderingsgrinden

Exempelanrop

Exempelsvar

Ta emot AI-agentkörningar

Exempelanrop

Exempelsvar

Ta emot händelser i en körning

Exempelanrop

Exempelsvar

Lista AI-agentkörningar

Exempelanrop

Exempelsvar

6. CI/CD-integration: utvärderingsgrinden

7. Maskinläsbar spec

8. Verifiera exporterade bevispaket

9. Versionering och deprecering

10. Angränsande dokumentation

11. Support

Public REST API

1. Autentisering

2. Behörighetsmodell

3. Anropstak

4. Felhantering

5. Endpoints

Skapa incident

Exempelanrop

Exempelsvar

Lista incidenter

Exempelanrop

Exempelsvar

Hämta incident

Exempelanrop

Exempelsvar

Skapa tillgång

Exempelanrop

Exempelsvar

Lista tillgångar

Exempelanrop

Exempelsvar

Skapa leverantör

Exempelanrop

Exempelsvar

Lista leverantörer

Exempelanrop