Authentication

All API requests require an active Supabase session. Authentication is handled via cookie-based auth — the sb-access-token and sb-refresh-token cookies are set automatically when a user signs in through the OneComply web application.

Every request is validated server-side via requireOrgContext(), which verifies the session and resolves the user's organization. Requests without a valid session receive a 401 Unauthorized response.

Role-based access control (RBAC) is enforced per endpoint. A 403 Forbidden response indicates the authenticated user lacks the required permission for the operation.

// Example: cookies are sent automatically by the browser.
// For programmatic access, forward the session cookies:
fetch("/api/vendors?page=1", {
  credentials: "include",
  headers: { "Content-Type": "application/json" }
});

Pagination

List endpoints support cursor-free pagination via ?page= and ?limit= query parameters. If the page parameter is omitted, the endpoint returns the full unpaginated array for backward compatibility.

Parameter	Type	Required	Description
page	integer	Optional	Page number (1-based). Activates paginated response.
limit	integer	Optional	Items per page. Default: 50. Max: 100.

Response Envelope

{
  "data": [
    { "id": "abc-123", "name": "CloudStore AG", ... }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 127,
    "totalPages": 3,
    "hasMore": true
  }
}

Vendors

Manage third-party vendor records, risk assessments, and DORA Art. 28-30 compliance.

GET/api/vendors

List all vendors for the current organization. Supports pagination, search, and filtering.

Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number (activates paginated response)
limit	integer	Optional	Items per page (default: 50)
search	string	Optional	Filter vendors by name (case-insensitive)

Example Response

{
  "data": [
    {
      "id": "clx9abc123",
      "name": "CloudStore AG",
      "service": "Cloud Hosting",
      "category": "Infrastructure",
      "criticality": "CRITICAL",
      "status": "APPROVED",
      "dataAccess": "FULL",
      "riskScore": 78,
      "riskLevel": "HIGH",
      "country": "DE",
      "isICTProvider": true,
      "isCloudProvider": true,
      "createdAt": "2025-03-15T10:30:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 24, "totalPages": 1, "hasMore": false }
}

POST/api/vendors

Create a new vendor record. Criticality and risk scores are auto-calculated from the provided fields. Also supports bulk import by sending an array of vendor objects.

Parameters

Parameter	Type	Required	Description
name	string	Required	Vendor name
service	string	Optional	Service provided
category	string	Optional	Vendor category (e.g. Infrastructure, SaaS)
dataAccess	string	Optional	Data access level: NONE, LIMITED, SIGNIFICANT, FULL
criticality	string	Optional	Override criticality: CRITICAL, IMPORTANT, STANDARD, LOW
country	string	Optional	ISO country code (e.g. DE, LU, US)
contactEmail	string	Optional	Primary contact email
contactName	string	Optional	Primary contact name
isICTProvider	boolean	Optional	Whether vendor is an ICT provider
isCloudProvider	boolean	Optional	Whether vendor is a cloud provider

Example Response

{
  "id": "clx9abc456",
  "name": "SecureVault GmbH",
  "service": "Data Backup",
  "category": "Infrastructure",
  "criticality": "IMPORTANT",
  "status": "PENDING",
  "dataAccess": "SIGNIFICANT",
  "riskScore": 62,
  "riskLevel": "MEDIUM",
  "country": "LU",
  "createdAt": "2025-06-01T14:20:00.000Z"
}

PATCH/api/vendors/[id]

Update an existing vendor record. Send only the fields that should change.

Parameters

Parameter	Type	Required	Description
id	string	Required	Vendor ID (URL path parameter)

Example Response

{
  "id": "clx9abc123",
  "name": "CloudStore AG",
  "status": "APPROVED",
  "updatedAt": "2025-06-02T09:15:00.000Z"
}

DELETE/api/vendors/[id]

Soft-delete a vendor. The record is marked with a deletedAt timestamp but not permanently removed, in compliance with DORA Art. 28 data retention requirements.

Parameters

Parameter	Type	Required	Description
id	string	Required	Vendor ID (URL path parameter)

Example Response

{
  "id": "clx9abc123",
  "deletedAt": "2025-06-03T11:00:00.000Z"
}

Controls

Manage compliance controls across DORA (120), ISO 27001 (93), NIS2 (45), GDPR (48), and CSSF 22/806 (35) frameworks.

GET/api/controls

List all controls for the current organization. Supports pagination, search, and framework filtering.

Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number (activates paginated response)
limit	integer	Optional	Items per page (default: 50)
search	string	Optional	Filter controls by title (case-insensitive)
framework	string	Optional	Filter by framework: DORA, ISO27001, NIS2

Example Response

{
  "data": [
    {
      "id": "clx9ctrl001",
      "code": "DORA-IRM-001",
      "title": "ICT Risk Management Framework",
      "description": "Establish and maintain an ICT risk management framework...",
      "framework": "DORA",
      "category": "ICT_RISK_MANAGEMENT",
      "priority": "CRITICAL",
      "status": "IMPLEMENTED",
      "reference": "art-5",
      "mappedTo": ["ISO-ORG-001"]
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 368, "totalPages": 8, "hasMore": true }
}

POST/api/controls

Initialize controls from the built-in library for a specific framework. Send { initFromTemplate: true, framework: 'DORA' } to bulk-create all controls for that framework. Omit framework to initialize all 378 controls.

Parameters

Parameter	Type	Required	Description
initFromTemplate	boolean	Required	Must be true to trigger bulk initialization
framework	string	Optional	DORA, ISO27001, NIS2, GDPR, CSSF22806, CRA, or omit for all

Example Response

{
  "initialized": 120,
  "framework": "DORA",
  "controls": [ ... ]
}

PATCH/api/controls/[id]

Update a control's status, assignment, due date, or other mutable fields.

Parameters

Parameter	Type	Required	Description
id	string	Required	Control ID (URL path parameter)
status	string	Optional	NOT_STARTED, IN_PROGRESS, IMPLEMENTED, EVIDENCED, AUDITED
assignedTo	string	Optional	User ID of the assigned owner
dueDate	string	Optional	ISO 8601 date string

Example Response

{
  "id": "clx9ctrl001",
  "code": "DORA-IRM-001",
  "status": "IMPLEMENTED",
  "assignedTo": "user_abc",
  "updatedAt": "2025-06-05T16:30:00.000Z"
}

Incidents

Track ICT incidents with DORA Art. 19 deadline management (4h / 72h / 1 month reporting windows).

GET/api/incidents

List all incidents. Supports pagination and search. Response includes enriched framework references separated into doraArticleRefs and controlRefs.

Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number (activates paginated response)
limit	integer	Optional	Items per page (default: 50)
search	string	Optional	Filter incidents by title (case-insensitive)

Example Response

{
  "data": [
    {
      "id": "clx9inc001",
      "title": "Cloud provider outage",
      "severity": "HIGH",
      "category": "Availability",
      "status": "OPEN",
      "isMajor": true,
      "detectedAt": "2025-06-10T08:00:00.000Z",
      "initialDeadline": "2025-06-10T12:00:00.000Z",
      "intermediateDeadline": "2025-06-13T08:00:00.000Z",
      "finalDeadline": "2025-07-10T08:00:00.000Z",
      "doraArticleRefs": ["art-17"],
      "controlRefs": ["DORA-IM-001"],
      "affectedUsers": 1200
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 8, "totalPages": 1, "hasMore": false }
}

POST/api/incidents

Create a new incident. For major incidents (isMajor: true), DORA Art. 19 reporting deadlines are auto-calculated from detectedAt.

Parameters

Parameter	Type	Required	Description
title	string	Required	Incident title
severity	string	Optional	LOW, MEDIUM, HIGH, CRITICAL (default: LOW)
category	string	Optional	Incident category (e.g. Availability, Confidentiality)
detectedAt	string	Required	ISO 8601 timestamp of when the incident was detected
isMajor	boolean	Optional	Whether this is a major incident (triggers DORA deadlines)
vendorId	string	Optional	Related vendor ID
impactDescription	string	Optional	Description of the impact
affectedSystems	string[]	Optional	List of affected system names
affectedUsers	integer	Optional	Number of affected users
financialImpact	number	Optional	Estimated financial impact in EUR

Example Response

{
  "id": "clx9inc002",
  "title": "Unauthorized data access attempt",
  "severity": "HIGH",
  "category": "Confidentiality",
  "isMajor": true,
  "detectedAt": "2025-06-12T14:30:00.000Z",
  "initialDeadline": "2025-06-12T18:30:00.000Z",
  "intermediateDeadline": "2025-06-15T14:30:00.000Z",
  "finalDeadline": "2025-07-12T14:30:00.000Z",
  "doraArticleRefs": ["art-17"],
  "controlRefs": [],
  "createdAt": "2025-06-12T14:35:00.000Z"
}

PATCH/api/incidents/[id]

Update an incident's status, severity, resolution details, or other mutable fields.

Parameters

Parameter	Type	Required	Description
id	string	Required	Incident ID (URL path parameter)

Example Response

{
  "id": "clx9inc001",
  "status": "RESOLVED",
  "resolvedAt": "2025-06-11T16:00:00.000Z",
  "updatedAt": "2025-06-11T16:00:00.000Z"
}

Policies

Manage compliance policies with version control, approval workflows, and review cycles.

GET/api/policies

List all policies for the current organization. Supports pagination and search.

Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number (activates paginated response)
limit	integer	Optional	Items per page (default: 50)
search	string	Optional	Filter policies by title (case-insensitive)

Example Response

{
  "data": [
    {
      "id": "clx9pol001",
      "title": "ICT Risk Management Policy",
      "status": "APPROVED",
      "version": 2,
      "framework": "DORA",
      "owner": "CISO",
      "approvedAt": "2025-05-20T10:00:00.000Z",
      "nextReviewDate": "2025-11-20T10:00:00.000Z",
      "createdAt": "2025-03-01T09:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 15, "totalPages": 1, "hasMore": false }
}

POST/api/policies

Create a new policy document. Policies start in DRAFT status.

Parameters

Parameter	Type	Required	Description
title	string	Required	Policy title
content	string	Optional	Policy body content (Markdown)
framework	string	Optional	Associated framework: DORA, ISO27001, NIS2
owner	string	Optional	Policy owner role or user

Example Response

{
  "id": "clx9pol002",
  "title": "Incident Response Procedure",
  "status": "DRAFT",
  "version": 1,
  "framework": "DORA",
  "createdAt": "2025-06-14T11:00:00.000Z"
}

PATCH/api/policies/[id]

Update a policy's content, status, or metadata. Status transitions follow the approval workflow: DRAFT -> IN_REVIEW -> APPROVED -> ARCHIVED.

Parameters

Parameter	Type	Required	Description
id	string	Required	Policy ID (URL path parameter)
status	string	Optional	DRAFT, IN_REVIEW, APPROVED, ARCHIVED
content	string	Optional	Updated policy body content

Example Response

{
  "id": "clx9pol002",
  "title": "Incident Response Procedure",
  "status": "APPROVED",
  "version": 2,
  "approvedAt": "2025-06-20T15:00:00.000Z",
  "updatedAt": "2025-06-20T15:00:00.000Z"
}

Compliance Score

Retrieve the current weighted compliance score with per-module breakdown and grading.

GET/api/compliance/score

Get the current compliance score for the organization, including per-module scores and an overall grade. The score is calculated across 6 modules: Controls, Vendors, Incidents, Policies, Evidence, and Tasks.

Example Response

{
  "overallScore": 82,
  "grade": "B",
  "modules": {
    "controls": { "score": 88, "grade": "A", "weight": 0.30 },
    "vendors": { "score": 75, "grade": "C", "weight": 0.20 },
    "incidents": { "score": 90, "grade": "A", "weight": 0.15 },
    "policies": { "score": 80, "grade": "B", "weight": 0.15 },
    "evidence": { "score": 70, "grade": "C", "weight": 0.10 },
    "tasks": { "score": 85, "grade": "B", "weight": 0.10 }
  },
  "updatedAt": "2025-06-15T00:00:00.000Z"
}

Health

System health check endpoint for monitoring and uptime verification.

GET/api/health

Returns the current system health status. Does not require authentication.

Example Response

{
  "status": "ok",
  "timestamp": "2025-06-15T12:00:00.000Z",
  "version": "1.0.0"
}

API Reference

Authentication

Pagination

Response Envelope

Vendors

Parameters

Example Response

Parameters

Example Response

Parameters

Example Response

Parameters

Example Response

Controls

Parameters

Example Response

Parameters

Example Response

Parameters

Example Response

Incidents

Parameters

Example Response

Parameters

Example Response

Parameters

Example Response

Policies

Parameters

Example Response

Parameters

Example Response

Parameters

Example Response

Compliance Score

Example Response

Health

Example Response