{
  "openapi": "3.1.0",
  "info": {
    "title": "CYBERWHITE read-only API",
    "version": "1.0.0",
    "summary": "Read your compliance data from another system.",
    "description": "Read-only. The API returns what the CYBERWHITE screens show for the clients your account can see. It cannot change a tenant, run a scan or deploy a fix. Limits: 60 requests a minute and 10000 a day per key.",
    "contact": {
      "name": "CYBERWHITE Support",
      "email": "support@cyberwhite.ai"
    }
  },
  "servers": [
    {
      "url": "https://cyberwhite.ai/api/v1"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "paths": {
    "/me": {
      "get": {
        "operationId": "getMe",
        "summary": "Test the connection and see the key's limits",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Me"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, not recognised, revoked or expired.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "API access is not enabled for this account.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Wait for the number of seconds in the Retry-After header.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/clients": {
      "get": {
        "operationId": "listClients",
        "summary": "List your clients",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "data",
                    "pagination",
                    "links"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Client"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "links": {
                      "$ref": "#/components/schemas/Links"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, not recognised, revoked or expired.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "API access is not enabled for this account.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Wait for the number of seconds in the Retry-After header.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/clients/{clientId}": {
      "get": {
        "operationId": "getClient",
        "summary": "Get one client",
        "parameters": [
          {
            "name": "clientId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Client"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, not recognised, revoked or expired.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "API access is not enabled for this account.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not one of this account's clients.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Wait for the number of seconds in the Retry-After header.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/clients/{clientId}/assessments": {
      "get": {
        "operationId": "listAssessments",
        "summary": "Latest result for each framework and level",
        "parameters": [
          {
            "name": "clientId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AssessmentSummary"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, not recognised, revoked or expired.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "API access is not enabled for this account.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not one of this account's clients.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Wait for the number of seconds in the Retry-After header.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/clients/{clientId}/assessments/{framework}": {
      "get": {
        "operationId": "getAssessment",
        "summary": "Control by control for one framework",
        "parameters": [
          {
            "name": "clientId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "framework",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "level",
            "in": "query",
            "description": "For example ML1 or Level3. Default: the most recent scan of the framework.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "compliant",
                "partial",
                "non_compliant",
                "needs_review",
                "licence_required"
              ],
              "description": "compliant: proven. partial / non_compliant: a proven gap. needs_review: the scan could not prove it either way. licence_required: the tenant lacks the Microsoft licence the check needs."
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "summary",
                    "data",
                    "pagination",
                    "links"
                  ],
                  "properties": {
                    "summary": {
                      "$ref": "#/components/schemas/AssessmentSummary"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Control"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "links": {
                      "$ref": "#/components/schemas/Links"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, not recognised, revoked or expired.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "API access is not enabled for this account.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not one of this account's clients.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Wait for the number of seconds in the Retry-After header.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/clients/{clientId}/gaps": {
      "get": {
        "operationId": "listGaps",
        "summary": "Only the controls that need work, highest priority first",
        "description": "Proven gaps only (partial and non_compliant). Accepted risks are included and flagged with riskAccepted, never hidden. Poll this to raise tickets.",
        "parameters": [
          {
            "name": "clientId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "framework",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "data",
                    "pagination",
                    "links"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Gap"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "links": {
                      "$ref": "#/components/schemas/Links"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, not recognised, revoked or expired.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "API access is not enabled for this account.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not one of this account's clients.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Wait for the number of seconds in the Retry-After header.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Is the API up?",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "status",
                    "apiVersion"
                  ],
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "apiVersion": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key created in Settings, Security Settings, API keys. Send it as \"Authorization: Bearer <key>\". Never put it in the URL."
      }
    },
    "schemas": {
      "Client": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name",
          "industry",
          "connected",
          "lastScannedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "industry": {
            "type": [
              "string",
              "null"
            ]
          },
          "connected": {
            "type": "boolean",
            "description": "A Microsoft 365 tenant is connected for this client."
          },
          "lastScannedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "AssessmentSummary": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "framework",
          "level",
          "lastScannedAt",
          "score",
          "counts"
        ],
        "properties": {
          "framework": {
            "type": "string",
            "examples": [
              "essential8-ml1",
              "essential8-ml2",
              "smb1001",
              "soc2"
            ]
          },
          "level": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "ML1",
              "Level3"
            ]
          },
          "lastScannedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Compliant controls as a percentage of all controls."
          },
          "counts": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "total",
              "compliant",
              "gaps",
              "needsReview",
              "licenceRequired",
              "attested"
            ],
            "properties": {
              "total": {
                "type": "integer"
              },
              "compliant": {
                "type": "integer"
              },
              "gaps": {
                "type": "integer"
              },
              "needsReview": {
                "type": "integer"
              },
              "licenceRequired": {
                "type": "integer"
              },
              "attested": {
                "type": "integer"
              }
            }
          }
        }
      },
      "Control": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "controlId",
          "name",
          "status",
          "detail",
          "source",
          "riskAccepted",
          "riskAcceptedAt",
          "priorityScore"
        ],
        "properties": {
          "controlId": {
            "type": "string",
            "description": "The framework's own control id, for example ML1-PO-02 or 1.8.0.0."
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "compliant",
              "partial",
              "non_compliant",
              "needs_review",
              "licence_required"
            ],
            "description": "compliant: proven. partial / non_compliant: a proven gap. needs_review: the scan could not prove it either way. licence_required: the tenant lacks the Microsoft licence the check needs."
          },
          "detail": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the scan found, in plain English, or the attestation note."
          },
          "source": {
            "type": "string",
            "enum": [
              "scan",
              "attestation"
            ],
            "description": "attestation means a person answered this control; the answer overrides the scan."
          },
          "riskAccepted": {
            "type": "boolean",
            "description": "True when a risk acceptance is currently recorded for this gap. The status is unchanged."
          },
          "riskAcceptedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "priorityScore": {
            "type": [
              "number",
              "null"
            ],
            "description": "CARS score recorded by the scan, where the scan recorded one. Higher is more urgent."
          }
        }
      },
      "Gap": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "controlId",
          "name",
          "status",
          "detail",
          "source",
          "riskAccepted",
          "riskAcceptedAt",
          "priorityScore",
          "framework",
          "level",
          "lastScannedAt"
        ],
        "properties": {
          "controlId": {
            "type": "string",
            "description": "The framework's own control id, for example ML1-PO-02 or 1.8.0.0."
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "compliant",
              "partial",
              "non_compliant",
              "needs_review",
              "licence_required"
            ],
            "description": "compliant: proven. partial / non_compliant: a proven gap. needs_review: the scan could not prove it either way. licence_required: the tenant lacks the Microsoft licence the check needs."
          },
          "detail": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the scan found, in plain English, or the attestation note."
          },
          "source": {
            "type": "string",
            "enum": [
              "scan",
              "attestation"
            ],
            "description": "attestation means a person answered this control; the answer overrides the scan."
          },
          "riskAccepted": {
            "type": "boolean",
            "description": "True when a risk acceptance is currently recorded for this gap. The status is unchanged."
          },
          "riskAcceptedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "priorityScore": {
            "type": [
              "number",
              "null"
            ],
            "description": "CARS score recorded by the scan, where the scan recorded one. Higher is more urgent."
          },
          "framework": {
            "type": "string"
          },
          "level": {
            "type": [
              "string",
              "null"
            ]
          },
          "lastScannedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "Pagination": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "limit",
          "offset",
          "total"
        ],
        "properties": {
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "Links": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "next"
        ],
        "properties": {
          "next": {
            "type": [
              "string",
              "null"
            ],
            "description": "Path of the next page, or null on the last page."
          }
        }
      },
      "Me": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "key",
          "clientCount",
          "limits",
          "apiVersion"
        ],
        "properties": {
          "key": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "name",
              "prefix",
              "expiresAt",
              "scopes"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "prefix": {
                "type": "string"
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time"
              },
              "scopes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "clientCount": {
            "type": "integer"
          },
          "limits": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "requestsPerMinute",
              "requestsPerDay"
            ],
            "properties": {
              "requestsPerMinute": {
                "type": "integer"
              },
              "requestsPerDay": {
                "type": "integer"
              }
            }
          },
          "apiVersion": {
            "type": "string"
          }
        }
      },
      "Problem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "requestId"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "requestId": {
            "type": "string",
            "format": "uuid"
          }
        }
      }
    }
  }
}
