API-dokumentation

Tenant-API v1 för system som läser din organisations register och skickar evidens. Sidan genereras från OpenAPI 3.1-specifikationen.

API-version: 1.0.0

Ladda ner OpenAPI-specifikationen (YAML)

Specifikationen och en guide med exempel finns också i produkten under Inställningar > API.

Autentisering och behörigheter

  • Basadress: https://<din-domän>/api/v1
  • Skicka token som Authorization: Bearer <token>. Token visas en gång när den skapas.
  • En token tillhör ett tjänstekonto, en icke-personlig användare som aldrig kan logga in. Den skapas av en superadmin under Inställningar > API.
  • Varje token har behörigheter (abilities), ett utgångsdatum (högst 12 månader fram, token utan utgångsdatum nekas) och kan begränsas till IP-adresser eller CIDR-intervall.
  • Varje anrop, även nekade, loggas i revisionsloggen (metod, sökväg utan frågesträng, status och adress).

Behörigheter

read:risks, read:assets, read:controls, read:vendors, read:audit, read:kri, read:evidence, write:evidence

Gränser och paginering

  • Timgräns per token, som standard 600 anrop. När gränsen är nådd svarar API:t 429 med rubriken Retry-After.
  • Listor använder markörbaserad paginering sorterad på updated_at och id. Använd per_page (1 till 200, standard 50) och följ links.next, eller skicka meta.next_cursor som cursor, tills värdet är null.
  • filter[updated_after] returnerar rader uppdaterade vid eller efter tidpunkten, för inkrementell synk.

Felformat

Fel har alltid denna form:

{ "success": false, "error": { "code": "validation_failed", "message": "...", "details": { "field": ["..."] } } }
  • 401 Token saknas, är okänd eller har gått ut.
  • 403 Behörighet saknas, token tillhör inte ett tjänstekonto eller adressen är inte tillåten.
  • 422 Valideringsfel. error.details kopplar fält till meddelanden.
  • 429 Timgränsen är förbrukad.

Endpoints

Method Path Behörighet  
GET /api/v1/risks read:risks List risks
GET /api/v1/assets read:assets List information assets
GET /api/v1/controls read:controls List controls of the current statements of applicability with effectiveness
GET /api/v1/vendors read:vendors List suppliers
GET /api/v1/findings read:audit List audit findings
GET /api/v1/kri read:kri List indicators (KRI, KCI, KPI)
GET /api/v1/evidence read:evidence List evidence items
POST /api/v1/evidence write:evidence Submit evidence for a control

GET /api/v1/risks

List risks

Behörighet: read:risks · Svarskoder: 200, 401, 403, 422, 429

Parametrar

NamnPlatsTypBeskrivning
per_pagequeryinteger
cursorquerystringThe meta.next_cursor of the previous page.
filter[updated_after]querystring (date-time)Only rows updated at or after this time (inclusive, so the newest updated_at you hold can be passed back; deduplicate on id).
Svarsfält (data) (20)
FältTypBeskrivning
idinteger
titlestring
descriptionstring
categorystring | null
risk_typestring | null
statusstring
likelihood_inherentinteger
impact_inherentinteger
score_inherentinteger
risk_levelstring
likelihood_residualinteger | null
impact_residualinteger | null
score_residualinteger | null
residual_risk_levelstring | null
appetite_statusstring | null
is_emergingboolean
ownerobject | null
owner_confirmed_atstring | null (date-time)
created_atstring (date-time)
updated_atstring (date-time)

GET /api/v1/assets

List information assets

Behörighet: read:assets · Svarskoder: 200, 401, 403, 422, 429

Parametrar

NamnPlatsTypBeskrivning
per_pagequeryinteger
cursorquerystringThe meta.next_cursor of the previous page.
filter[updated_after]querystring (date-time)Only rows updated at or after this time (inclusive, so the newest updated_at you hold can be passed back; deduplicate on id).
Svarsfält (data) (19)
FältTypBeskrivning
idinteger
uuidstring
asset_identifierstring | null
namestring
descriptionstring | null
categorystring | null
statusstring
confidentiality_levelinteger | null
integrity_levelinteger | null
availability_levelinteger | null
overall_classificationinteger | null
business_criticalitystring | null
is_essential_serviceboolean
is_important_serviceboolean
ownerobject | null
classification_datestring | null (date)
next_review_datestring | null (date)
created_atstring (date-time)
updated_atstring (date-time)

GET /api/v1/controls

List controls of the current statements of applicability with effectiveness

Behörighet: read:controls · Svarskoder: 200, 401, 403, 422, 429

Parametrar

NamnPlatsTypBeskrivning
per_pagequeryinteger
cursorquerystringThe meta.next_cursor of the previous page.
filter[updated_after]querystring (date-time)Only rows updated at or after this time (inclusive, so the newest updated_at you hold can be passed back; deduplicate on id).
Svarsfält (data) (18)
FältTypBeskrivning
idinteger
soa_document_idinteger
frameworkstring | null
control_codestring | null
titlestring | null
is_applicableboolean
implementation_statusstring | null
is_key_controlboolean
frequencystring | null
design_effectivenessstring
design_assessed_atstring | null (date-time)
operating_effectivenessstring
operating_tested_atstring | null (date-time)
operating_test_period_startstring | null (date)
operating_test_period_endstring | null (date)
verifiedbooleanEffective operation counts only with valid evidence and no active exception.
exceptedboolean
updated_atstring (date-time)

GET /api/v1/vendors

List suppliers

Behörighet: read:vendors · Svarskoder: 200, 401, 403, 422, 429

Parametrar

NamnPlatsTypBeskrivning
per_pagequeryinteger
cursorquerystringThe meta.next_cursor of the previous page.
filter[updated_after]querystring (date-time)Only rows updated at or after this time (inclusive, so the newest updated_at you hold can be passed back; deduplicate on id).
Svarsfält (data) (20)
FältTypBeskrivning
idinteger
namestring
organization_numberstring | null
vendor_typestring | null
criticalitystring | null
statusstring | null
countrystring | null
inherent_risk_scorenumber | null
residual_risk_scorenumber | null
last_assessed_atstring | null (date-time)
next_assessment_duestring | null (date-time)
contract_start_datestring | null (date)
contract_end_datestring | null (date)
processes_personal_databoolean
is_ict_providerboolean
supports_critical_functionboolean
certificationsarray | null
ownerobject | null
created_atstring (date-time)
updated_atstring (date-time)

GET /api/v1/findings

List audit findings

Behörighet: read:audit · Svarskoder: 200, 401, 403, 422, 429

Parametrar

NamnPlatsTypBeskrivning
per_pagequeryinteger
cursorquerystringThe meta.next_cursor of the previous page.
filter[updated_after]querystring (date-time)Only rows updated at or after this time (inclusive, so the newest updated_at you hold can be passed back; deduplicate on id).
Svarsfält (data) (18)
FältTypBeskrivning
idinteger
uuidstring
audit_idinteger
finding_typestring
severitystring
statusstring
control_idstring | null
titlestring
descriptionstring | null
audit_criteria_referencestring | null
corrective_action_requiredboolean
due_datestring | null (date)
resolved_atstring | null (date-time)
verified_atstring | null (date-time)
withdrawn_atstring | null (date-time)
assigned_toobject | null
created_atstring (date-time)
updated_atstring (date-time)

GET /api/v1/kri

List indicators (KRI, KCI, KPI)

Behörighet: read:kri · Svarskoder: 200, 401, 403, 422, 429

Parametrar

NamnPlatsTypBeskrivning
per_pagequeryinteger
cursorquerystringThe meta.next_cursor of the previous page.
filter[updated_after]querystring (date-time)Only rows updated at or after this time (inclusive, so the newest updated_at you hold can be passed back; deduplicate on id).
Svarsfält (data) (19)
FältTypBeskrivning
idinteger
uuidstring
namestring
indicator_typestring
unitstring | null
statusstring
measurement_frequencystring | null
threshold_directionstring | null
threshold_greennumber | null
threshold_yellownumber | null
threshold_rednumber | null
current_valuenumber | null
current_zonestring
zone_sincestring | null (date-time)
days_in_current_zoneinteger | null
last_measurement_atstring | null (date-time)
ownerobject | null
created_atstring (date-time)
updated_atstring (date-time)

GET /api/v1/evidence

List evidence items

Behörighet: read:evidence · Svarskoder: 200, 401, 403, 422, 429

Parametrar

NamnPlatsTypBeskrivning
per_pagequeryinteger
cursorquerystringThe meta.next_cursor of the previous page.
filter[updated_after]querystring (date-time)Only rows updated at or after this time (inclusive, so the newest updated_at you hold can be passed back; deduplicate on id).
Svarsfält (data) (18)
FältTypBeskrivning
idstring
control_idstring | null
frameworkstring | null
titlestring
descriptionstring | null
categorystring | null
source_typestring
source_systemstring | null
external_referencestring | null
sha256string | null
statusstring
resultstring | nullVerdict of an automatic check. The collected data is never returned.
has_fileboolean
collected_atstring (date-time)
expires_atstring | null (date-time)
is_expiredboolean
created_atstring (date-time)
updated_atstring (date-time)

POST /api/v1/evidence

Submit evidence for a control

Behörighet: write:evidence · Svarskoder: 200, 201, 401, 403, 422, 429

Begäran (fält) (JSON eller multipart/form-data)

FältTypObligatoriskBeskrivning
control_idstringjaCatalog code of the control.
frameworkstringjaFramework label or slug, for example iso27001.
source_systemstringja
collected_atstring (date-time)jaNot more than five minutes in the future.
titlestringja
descriptionstring
categorystring
expires_atstring (date-time)After collected_at.
external_referencestringThe sending system's own reference; makes retries safe.
dataobjectjaStructured content (at most 1 MiB). Send this or a file.

Evidens är proveniens, aldrig en deklarerad status: ett anrop kan inte ändra en kontrolls implementations- eller effektivitetsstatus.

Svarsfält (data) (18)
FältTypBeskrivning
idstring
control_idstring | null
frameworkstring | null
titlestring
descriptionstring | null
categorystring | null
source_typestring
source_systemstring | null
external_referencestring | null
sha256string | null
statusstring
resultstring | nullVerdict of an automatic check. The collected data is never returned.
has_fileboolean
collected_atstring (date-time)
expires_atstring | null (date-time)
is_expiredboolean
created_atstring (date-time)
updated_atstring (date-time)

Kontakt för frågor om API:t: info@securapilot.com

Vi använder anonym statistik utan cookies för att förbättra webbplatsen. Läs mer