openapi: 3.0.3 info: version: 0.0.1 title: CyCognito API V1 Reference Assets Cloud Connectors API description: 'The CyCognito API V1 is a REST API that allows you to post and get data from our main data entities—assets and issues. You can also manage the scope of your attack surface, attribute assets to organizations, and verify the identity of IP scans on your assets. Our legacy API (V0) documentation is available for download [here](https://platform.cycognito.com/CyCognito-API-V0-Reference.pdf). While V0 is still being supported, please note that this API is undergoing deprecation. | Code | Name | Description | |------|------|-------------| | 200 | OK | Success | | 400 | Bad Request | The request is malformed—e.g., the body cannot be properly parsed, expected fields are not included in the body, or unsupported request header values. | | 403 | Access Restricted | There are insufficient permissions or a valid API key was not provided. | | 404 | Not Found | The provided resource was not found. | | 405 | Method Not Allowed | The HTTP method is not allowed for the given resource. | | 415 | Unsupported Media Type | The request content type is not supported. | | 5XX | | Server failure | | ' tags: - name: Cloud Connectors paths: /v1/cloud-environments: get: description: Retrieve a list of cloud environments. security: - apiAuth: [] summary: Retrieve multiple cloud environment data tags: - Cloud Connectors responses: '200': content: application/json: schema: anyOf: - type: array items: type: object properties: id: description: A unique identifier for the cloud environment. This ID can be extrapolated from the `cloud-env-id` field (from the *Add new connector* response) by removing the `cloud-env/` prefix. type: string example: 12312-3213-12341 test-status: description: Indicates whether the connector was configured correctly or not. type: string example: Success provider: description: The name of the cloud service provider (e.g., AWS). **Note:** Currently only AWS is supported. type: string enum: - AWS - Azure - GCP - Cloudflare - WIZ example: AWS cloud-env-name: description: A name used solely for identifying the cloud connector and the environment connected to it. type: string example: Acme AWS cloud environment required: - id - test-status - provider - cloud-env-name - type: object properties: exception: description: Indicates whether the specified cloud environment exists or not. type: string required: - exception post: description: Create a new cloud environment for the specified provider. **Note:** This endpoint currently only supports setting up connectors for single AWS accounts. The accompanying YAML script can be downloaded via the link generated by the *Get YAML for AWS* API endpoint. security: - apiAuth: [] summary: Add new AWS connector tags: - Cloud Connectors requestBody: content: application/json: schema: type: object properties: connector-name: description: 'A name used solely for identifying the cloud connector and the environment connected to it. It is recommended to provide a unique name which helps identify the cloud environment to which it is connected. Cloud connector names are limited to 50 characters, and may contain only alphanumeric characters and the following special characters: `-_()[]`' type: string organization-attribution: description: The name of the organization that all cloud-fetched assets will be attributed to. type: string provider: description: The name of the cloud service provider (i.e., AWS). type: string enum: - aws provider-details: description: Details specific to the provider. type: object properties: account-id: description: Your AWS account ID. Learn how to find this 12-digit number by reading the AWS documentation. type: string arn: description: 'The Amazon Resource Name (ARN). The formatted [ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html) will look like: `arn:aws:iam::123456789012:role/CyCognitoCloudConnector-a123b4567c`.' type: string required: - account-id - arn required: - connector-name - organization-attribution - provider - provider-details example: "{\n \"connector-name\": \"Acme AWS Cloud Environment\",\n \"organization-attribution\": \"Acme Corporation\",\n \"provider\": \"aws\",\n \"provider-details\": {\n \"account-id\": \"123456789012\",\n \"arn\": \"arn:aws:iam::123456789012:role/CyCognitoCloudConnector-a123b4567c\"\n }\n}" responses: '200': content: application/json: schema: anyOf: - type: object properties: cloud-env-id: description: A unique identifier for the cloud environment. This ID can be extrapolated from the `cloud-env-id` field (from the *Add new connector* response) by removing the `cloud-env/` prefix (e.g., `12312-3213-12341`). type: string required: - cloud-env-id - type: object properties: error: description: A message describing the reason for the failure. type: string required: - error /v1/cloud-environments/script: post: description: Generate the YAML script required for creating new AWS connectors. security: - apiAuth: [] summary: Get YAML for AWS tags: - Cloud Connectors requestBody: content: application/json: schema: type: object properties: provider: description: The name of the cloud service provider (i.e., AWS). type: string enum: - aws privilege: description: Determines the permission level granted to the Connector ('regular' or 'least'). type: string enum: - regular - least required: - provider - privilege responses: '200': {} /v1/cloud-environments/{cloud-env-id}: get: description: Fetch data for a single cloud environment. security: - apiAuth: [] summary: Retrieve single cloud environment data tags: - Cloud Connectors parameters: - name: cloud-env-id in: path schema: type: string required: true description: A unique identifier for the cloud environment. This ID can be extrapolated from the `cloud-env-id` field (from the *Add new connector* response) by removing the `cloud-env/` prefix (e.g., `12312-3213-12341`). responses: '200': content: application/json: schema: anyOf: - type: object properties: id: description: A unique identifier for the cloud environment. This ID can be extrapolated from the `cloud-env-id` field (from the *Add new connector* response) by removing the `cloud-env/` prefix. type: string example: 12312-3213-12341 test-status: description: Indicates whether the connector was configured correctly or not. type: string example: Success provider: description: The name of the cloud service provider (e.g., AWS). **Note:** Currently only AWS is supported. type: string enum: - AWS - Azure - GCP - Cloudflare - WIZ example: AWS cloud-env-name: description: A name used solely for identifying the cloud connector and the environment connected to it. type: string example: Acme AWS cloud environment required: - id - test-status - provider - cloud-env-name - type: object properties: exception: description: Indicates whether the specified cloud environment exists or not. type: string required: - exception /v1/cloud-environments/{cloud-env-id}/test-connector: put: description: Trigger a test to determine whether the specified cloud connector is configured correctly. security: - apiAuth: [] summary: Test connector tags: - Cloud Connectors parameters: - name: cloud-env-id in: path schema: type: string required: true description: A unique identifier for the cloud environment. This ID can be extrapolated from the `cloud-env-id` field (from the *Add new connector* response) by removing the `cloud-env/` prefix (e.g., `12312-3213-12341`). responses: '200': content: application/json: schema: type: object properties: message: description: A message indicating the result of the test. type: string example: Cloud environment test completed successfully. status: description: The status of the test, either *completed* or *failed*. type: string enum: - completed - failed example: completed required: - message - status components: securitySchemes: apiAuth: type: apiKey name: Authorization in: header