Settings

Managing Conformity settings.

Get Communication Setting Details

get/settings/{settingId}

This endpoint allows you to get the details of the specified communication setting.

IMPORTANT: Users with different roles can get different results from this endpoint.

The table below describes the relationship between user role or account access level, and type of data the user can get for account level settings.

Role / access to the account Account-Level Settings
ADMIN Full settings with configuration
FULL access to the account Full setting with configurations
READONLY access to the account Setting without configurations
NO access to the account No setting

For organisation level settings, the ADMIN users are the only users who can access those settings. The table below describes the relationship between user role and type of the data user can get for organisation level settings.

Role Organisation-Level Settings
ADMIN Full settings with configuration
POWER USER No setting
READONLY No setting
USER No setting

Example Request:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
https://us-west-2-api.cloudconformity.com/v1/settings/ryqs8LNKW:communication:email-Ske1cKKEvM

Example Response:

{
    "data": {
        "type": "settings",
        "id": "ryqs8LNKW:communication:email-Ske1cKKEvM",
        "attributes": {
            "type": "communication",
            "manual": false,
            "enabled": true,
            "filter": {
                "categories": [
                    "security"
                ],
                "suppressed": false
            },
            "configuration": {
                "users": [
                    "HyL7K6GrZ"
                ]
            },
            "channel": "email"
        },
        "relationships": {
            "organisation": {
                "data": {
                    "type": "organisations",
                    "id": "ryqMcJn4b"
                }
            },
            "account": {
                "data": {
                    "type": "accounts",
                    "id": "H19NxM15-"
                }
            }
        }
    }
}
SecurityApiKeyAuth
Request
path Parameters
settingId
required
string

Cloud Conformity ID of the communication setting.

Example: communication:email-57DryxMDh
Responses
200

Successful response.

400

Bad Request.

401

Unauthorized. The requested user does not have enough privilege.

403

Forbidden. This happens when an invalid api key is provided or the user does not have access to the api keys.

500

Internal Server Error

Response samples
application/json
{
  • "data": {
    }
}

Delete Communication Setting

delete/settings/{settingId}

This endpoint allows a user to delete a communication setting.

Important: User role defines how they may use this endpoint:

  1. Only ADMIN users can delete organisation-level settings.
  2. For an account-level setting, both ADMINs and users with FULL access to the account can delete it.
SecurityApiKeyAuth
Request
path Parameters
settingId
required
string

Cloud Conformity ID of the communication setting.

Example: communication:email-57DryxMDh
Responses
200

200 response

400

Bad Request.

401

Unauthorized. The requested user does not have enough privilege.

403

Forbidden. This happens when an invalid api key is provided or the user does not have access to the api keys.

404

Not Found.

500

Internal Server Error

Response samples
application/json
{
  • "meta": {
    }
}

Get Communication Settings

get/settings/communication

A GET request to this endpoint allows you to get communication settings. This feature can be used in conjunction with a POST request to copy communication settings from one account to others.

IMPORTANT:    Users with different roles can get different results from this endpoint.

The table below describes the relationship between user role or account access level, and type of data the user can get for account level settings.

Role / access to the account Account-Level Settings
ADMIN Full settings with configuration
FULL access to the account Full setting with configurations
READONLY access to the account Setting without configurations
NO access to the account No setting

For organisation level settings, the ADMIN users are the only users who can access those settings. The table below describes the relationship between user role and type of the data user can get for organisation level settings.

Role Organisation-Level Settings
ADMIN Full settings with configuration
POWER USER No setting
READONLY No setting
USER No setting

Example request for email-only settings:


curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
https://us-west-2-api.cloudconformity.com/v1/settings/communication?accountId=H19NxM15-&channel=email&includeParents=true

Example Response for an ADMIN user: (Note: The first object is for an organisation-level setting: setting.relationships.account.data is NULL)

{
    "data": [
        {
            "type": "settings",
            "id": "communication:email-HJgeFWmpVf",
            "attributes": {
                "type": "communication",
                "manual": false,
                "enabled": true,
                "filter": {
                    "services": [
                        "Organizations"
                    ],
                    "suppressed": false
                },
                "configuration": {
                    "users": [
                        "BJlqMqknVb"
                    ]
                },
                "channel": "email"
            },
            "relationships": {
                "organisation": {
                    "data": {
                        "type": "organisations",
                        "id": "ryqMcJn4b"
                    }
                },
                "account": {
                    "data": null
                }
            }
        },
        {
            "type": "settings",
            "id": "ryqs8LNKW:communication:email-Ske1cKKEvM",
            "attributes": {
                "type": "communication",
                "manual": false,
                "enabled": true,
                "filter": {
                    "categories": [
                        "security"
                    ],
                    "suppressed": false
                },
                "configuration": {
                    "users": [
                        "HyL7K6GrZ"
                    ]
                },
                "channel": "email"
            },
            "relationships": {
                "organisation": {
                    "data": {
                        "type": "organisations",
                        "id": "ryqMcJn4b"
                    }
                },
                "account": {
                    "data": {
                        "type": "accounts",
                        "id": "H19NxM15-"
                    }
                }
            }
        }
    ]
}

Example response for a user with FULL access to the acount: (Note: The list does not contain organisation-level settings as only ADMIN users have access to organisation-level settings).

{
    "data": [
        {
            "type": "settings",
            "id": "ryqs8LNKW:communication:email-Ske1cKKEvM",
            "attributes": {
                "type": "communication",
                "manual": false,
                "enabled": true,
                "filter": {
                    "categories": [
                        "security"
                    ],
                    "suppressed": false
                },
                "configuration": {
                    "users": [
                        "HyL7K6GrZ"
                    ]
                },
                "channel": "email"
            },
            "relationships": {
                "organisation": {
                    "data": {
                        "type": "organisations",
                        "id": "ryqMcJn4b"
                    }
                },
                "account": {
                    "data": {
                        "type": "accounts",
                        "id": "H19NxM15-"
                    }
                }
            }
        }
    ]
}

Example request for organisation-level email-only settings:


curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
https://us-west-2-api.cloudconformity.com/v1/settings/communication?channel=email

Example Response for an ADMIN user:

{
    "data": [
        {
            "type": "settings",
            "id": "communication:email-HJgeFWmpVf",
            "attributes": {
                "type": "communication",
                "manual": false,
                "enabled": true,
                "filter": {
                    "services": [
                        "Organizations"
                    ],
                    "suppressed": false
                },
                "configuration": {
                    "users": [
                        "BJlqMqknVb"
                    ]
                },
                "channel": "email"
            },
            "relationships": {
                "organisation": {
                    "data": {
                        "type": "organisations",
                        "id": "ryqMcJn4b"
                    }
                },
                "account": {
                    "data": null
                }
            }
        }
    ]
}

Example request for account-level email-only settings:


curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
https://us-west-2-api.cloudconformity.com/v1/settings/communication?accountId=H19NxM15-&channel=email

Example Response for an ADMIN user: (Note: Without the includeParents parameter, no organisation-level settings are shown.)

{
    "data": [
        {
            "type": "settings",
            "id": "ryqs8LNKW:communication:email-Ske1cKKEvM",
            "attributes": {
                "type": "communication",
                "manual": false,
                "enabled": true,
                "filter": {
                    "categories": [
                        "security"
                    ],
                    "suppressed": false
                },
                "configuration": {
                    "users": [
                        "HyL7K6GrZ"
                    ]
                },
                "channel": "email"
            },
            "relationships": {
                "organisation": {
                    "data": {
                        "type": "organisations",
                        "id": "ryqMcJn4b"
                    }
                },
                "account": {
                    "data": {
                        "type": "accounts",
                        "id": "H19NxM15-"
                    }
                }
            }
        }
    ]
}
SecurityApiKeyAuth
Request
query Parameters
accountId
string

Cloud Conformity ID of the account. Provide to get only settings set for the specified account.

channel
string (communication-channels)

Communication channels.

Enum: "email" "sms" "slack" "pager-duty" "sns" "ms-teams" "webhook"
Example: channel=email
includeParents
boolean

Can only be used in conjunction with the accountId parameter. Specify true if you want to see both account level settings and organisation level settings.

Responses
200

Successful response.

400

Bad Request.

401

Unauthorized. The requested user does not have enough privilege.

403

Forbidden. This happens when an invalid api key is provided or the user does not have access to the api keys.

422

Unknown. This happens when parameter is unknown.

Response samples
application/json
{
  • "data": [
    ]
}

Create Communication Settings

post/settings/communication

This endpoint is used to create a new one-way communication channel setting. This feature can be used in conjunction with a GET request to copy communication settings from one account to others. An example of this function is provided in the examples folder.

IMPORTANT:    Some guidelines about using this endpoint:

  1. Settings are created as long as your inputs are valid. The onus is on you to ensure you don't create settings that are duplicate or too similar in nature.
  2. Each communication setting can be account-level OR organisation-level
    1. If creating account-level setting, you must have a valid relationship.account object.
    2. If creating organisation-level settings you must set relationship.account.data: null
    3. Only ADMIN users can create organisation-level settings.
    4. With organisation-level user-based (email & sms) settings, the onus is on you to ensure these users have at least read-only access to all accounts.

Filtering

The table below give more information about filter options:

Name Values
filter.regions An array of valid region strings. e.g. ["us-west-1", "us-west-2"], or ["eastus", "westus"]

For a complete list, please refer to Cloud Conformity Region Endpoint
filter.services An array of service strings. e.g.
AutoScaling | Kinesis | EFS

For a complete list, please refer to Cloud Conformity Services Endpoint
filter.ruleIds An array of valid rule Ids (e.g. ["S3-016", "EC2-001"]). For a complete list, please refer to Cloud Conformity Services Endpoint.
filter.categories An array of category (AWS well-architected framework category) strings from the following:
security | cost-optimisation | reliability | performance-efficiency | operational-excellence | sustainability
filter.riskLevels An array of risk-level strings from the following:
LOW| MEDIUM | HIGH | VERY_HIGH | EXTREME
filter.statuses (only used for SNS and webhook channels) An array of statuses strings from the following: SUCCESS | FAILURE
filter.tags An array of any assigned metadata tags to your resources (DEPRECATED)
filter.compliances An array of supported standard or framework ids. Possible values: ["AWAF" | "GCPWAF" | "CISAWSF-1_5_0" | "CISAWSF-2_0" | "CISAWSF-3_0" | "CISAZUREF-1_5_0" | "CISAZUREF-2_0" | "CISAZUREF-2_1" | "CISGCPF-1_3_0" | "CISGCPF-2_0" | "CISGCPF-3_0" | "CIS-V8" | "PCI" | "PCI-V4" | "HIPAA" | "GDPR" | "APRA" | "NIST4" | "NIST5" | "SOC2" | "NIST-CSF" | "NIST-CSF-2_0" | "ISO27001" | "ISO27001-2022" | "AGISM" | "HITRUST" | "ASAE-3150" | "MAS" | "FEDRAMP" | "ENISA" | "NIS-2" | "FISC-V9" | "LGPD" | "AZUREWAF-2024"]
filter.filterTags An array of any assigned metadata tags, tag keys or tag values to your AWS resources. e.g filterTags["dev"] will match resource with tag "environment::dev" in the filter

Configuration

The table below give more information about configuration options:

Channel Configuration
all configuration.channelName is the label to display in the application (to distinguish between multiple instances of the same channel type). It is optional
email configuration.key is "users", configuration.value is an array of verified users that have at least readOnly access to the account
sms configuration.key is "users", configuration.value is an array of users with verified mobile numbers that have at least readOnly access to the account
slack { "url": "https://hooks.slack.com/services/your-slack-webhook",
"channel": "#your-channel",
"displayIntroducedBy": false, Boolean, true for adding user to message
"displayResource": false, Boolean, true for adding resource to message
"displayTags": false Boolean, true for adding associated tags to message
"displayExtraData": false} Boolean, true for adding associated extra data to message
pager-duty { "serviceName": "yourServiceName", "serviceKey": "yourServiceKey" }
sns { "arn": "arn:aws:sns:REGION:ACCOUNT_ID:TOPIC_NAME"}
Note: Follow the steps on Setup Access for an SNS Topic on our help page.
ms-teams { "url": "https://organisationname.webhook.office.com/webhookb2/your-msteams-webhook-uuid",
"channel": "#your-channel",
"displayIntroducedBy": false, Boolean, true for adding user to message
"displayResource": false, Boolean, true for adding resource to message
"displayTags": false Boolean, true for adding associated tags to message
"displayExtraData": false} Boolean, true for adding associated extra data to message
webhook { "url": "https://your-webhook-url.com",
"securityToken": "yourSecurityToken",
headers[{"key": "yourHeaderKey"}, "value": "yourHeaderValue"]} Optional custom headers. Allow up to 5 custom headers.
SecurityApiKeyAuth
Request
Request Body schema: application/vnd.api+json
Array of communication-settings-email (object) or communication-settings-sms (object) or communication-settings-ms-teams (object) or communication-settings-slack (object) or communication-settings-sns (object) or communication-settings-pager-duty (object) or communication-settings-webhook (object) (request-14)

A JSON object containing JSONAPI compliant data object containing an array of email, sms, ms-teams, slack, sns, pager-duty, webhook communication settings.

Responses
200

Successful response.

400

Bad Request.

401

Unauthorized. The requesting user does not have enough privilege.

403

403 Forbidden

422

422 Unprocessable Entity

500

500 Internal Server Error

Request samples
application/vnd.api+json
{
  • "data": [
    ]
}
Response samples
application/json
[
  • {
    }
]

Update Communication Settings

patch/settings/communication/{settingId}

This endpoint allows you to update a specific communication setting.

IMPORTANT: User role defines how they may use this endpoint:

  1. Only ADMIN users can update organisation-level settings.
  2. For an account-level setting, both ADMINs and users with FULL access to the account can update it.

Filtering

The table below give more information about filter options:

Name Values
filter.regions An array of valid region strings. e.g. ["us-west-1", "us-west-2"], or ["eastus", "westus"]

For a complete list, please refer to Cloud Conformity Region Endpoint
filter.services An array of service strings. e.g.
AutoScaling | Kinesis | EFS

For a complete list, please refer to Cloud Conformity Services Endpoint
filter.ruleIds An array of valid rule Ids (e.g. ["S3-016", "EC2-001"]). For a complete list, please refer to Cloud Conformity Services Endpoint.
filter.categories An array of category (AWS well-architected framework category) strings from the following:
security | cost-optimisation | reliability | performance-efficiency | operational-excellence
filter.riskLevels An array of risk-level strings from the following:
LOW| MEDIUM | HIGH | VERY_HIGH | EXTREME
filter.statuses (only used for SNS and webhook channels) An array of statuses strings from the following: SUCCESS | FAILURE
filter.tags An array of any assigned metadata tags to your resources (DEPRECATED)
filter.compliances An array of supported standard or framework ids. Possible values: ["AWAF" | "GCPWAF" | "CISAWSF-1_5_0" | "CISAWSF-2_0" | "CISAWSF-3_0" | "CISAZUREF-1_5_0" | "CISAZUREF-2_0" | "CISAZUREF-2_1" | "CISGCPF-1_3_0" | "CISGCPF-2_0" | "CISGCPF-3_0" | "CIS-V8" | "CISAWSTTW" | "PCI" | "PCI-V4" | "HIPAA" | "GDPR" | "APRA" | "NIST4" | "NIST5" | "SOC2" | "NIST-CSF" | "NIST-CSF-2_0" | "ISO27001" | "ISO27001-2022" | "AGISM" | "HITRUST" | "ASAE-3150" | "MAS" | "FEDRAMP" | "ENISA" | "NIS-2" | "FISC-V9" | "LGPD" | "AZUREWAF-2024"]
filter.filterTags An array of any assigned metadata tags, tag keys or tag values to your AWS resources. e.g filterTags ["dev"] will match resource with tag "environment::dev" in the filter

Configuration

The table below give more information about configuration options:

Channel Configuration
all configuration.channelName is the label to display in the application (to distinguish between multiple instances of the same channel type). It is optional
email configuration.key is "users", configuration.value is an array of verified users that have at least readOnly access to the account
sms configuration.key is "users", configuration.value is an array of users with verified mobile numbers that have at least readOnly access to the account
slack { "url": "https://hooks.slack.com/services/your-slack-webhook",
"channel": "#your-channel",
"displayIntroducedBy": false, Boolean, true for adding user to message
"displayResource": false, Boolean, true for adding resource to message
"displayTags": false Boolean, true for adding associated tags to message
"displayExtraData": false} Boolean, true for adding associated extra data to message
pager-duty { "serviceName": "yourServiceName", "serviceKey": "yourServiceKey" }
sns { "arn": "arn:aws:sns:REGION:ACCOUNT_ID:TOPIC_NAME"}
Note: Follow the steps on Setup Access for an SNS Topic on our help page.
ms-teams { "url": "https://organisationname.webhook.office.com/webhookb2/your-msteams-webhook-uuid",
"channel": "#your-channel",
"displayIntroducedBy": false, Boolean, true for adding user to message
"displayResource": false, Boolean, true for adding resource to message
"displayTags": false Boolean, true for adding associated tags to message
"displayExtraData": false} Boolean, true for adding associated extra data to message
webhook { "url": "https://your-webhook-url.com",
"securityToken": "yourSecurityToken",
headers[{"key": "yourHeaderKey"}, "value": "yourHeaderValue"]} Optional custom headers. Allow up to 5 custom headers.

Example request to update an account level pager-duty setting:

curl -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
-d '
{
    "data": {
        "type": "settings",
        "attributes": {
            "type": "communication",
            "enabled": true,
            "configuration": {
                "serviceName": "SomeOtherName",
                "serviceKey": "anotherpagerdutyservicekey"
            },
            "channel": "pager-duty"
        }
    }
}' \
https://us-west-2-api.cloudconformity.com/v1/settings/communication/H19NxM15-:communication:pager-duty-S1xvk1zGwM

Example Response:

  [
    {
        "data": {
            "type": "settings",
            "id": "H19NxM15-:communication:pager-duty-S1xvk1zGwM",
            "attributes": {
                "type": "communication",
                "manual": "",
                "enabled": true,
                "configuration": {
                    "serviceName": "SomeOtherName",
                    "serviceKey": "anotherpagerdutyservicekey"
                },
                "channel": "pager-duty"
            },
            "relationships": {
                "organisation": {
                    "data": {
                        "type": "organisations",
                        "id": "ryqMcJn4b"
                    }
                },
                "account": {
                    "data": {
                        "type": "accounts",
                        "id": "H19NxM15-"
                    }
                }
            }
        }
    }
]
SecurityApiKeyAuth
Request
Request Body schema: application/vnd.api+json
Any of:

Email communication settings.

object

Object containing attributes type, channel, enabled, manual, filter, configuration.

object (communication-settings-relationships)
type
string (communication-settings-type)
Responses
200

Successful response.

400

Bad Request.

401

Unauthorized. The requesting user does not have enough privilege.

403

403 Forbidden

422

422 Unprocessable Entity

500

500 Internal Server Error

Request samples
application/vnd.api+json
{
  • "type": "settings",
  • "attributes": {
    },
  • "relationships": {
    }
}
Response samples
application/json
[
  • {
    }
]