Get Communication Setting Details
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-"
}
}
}
}
}
Successful response.
Bad Request.
Unauthorized. The requested user does not have enough privilege.
Forbidden. This happens when an invalid api key is provided or the user does not have access to the api keys.
Internal Server Error
- 200
- 400
- 401
- 403
- 500
{- "data": {
- "id": "communication:email-3JD1mkXfz",
- "attributes": {
- "created-by": "n6yTeW_lx",
- "created-date": 1565165403747,
- "is-account-level": false,
- "is-group-level": false,
- "is-organisation-level": true,
- "type": "communication",
- "enabled": true,
- "channel": "email",
- "filter": {
- "regions": "us-east-1",
- "services": [
- "EC2"
], - "ruleIds": [
- "S3-016"
], - "categories": [
- "security"
], - "riskLevels": [
- "HIGH"
], - "tags": [
- "tagName"
], - "filterTags": [
- "tagKey"
], - "compliances": [
- "AWAF"
]
}, - "configuration": {
- "users": [
- [
- "t-UoU9CsK"
]
]
}
}, - "type": "settings",
- "relationships": {
- "account": {
- "data": {
- "type": "accounts",
- "id": "H19NxM15-"
}
}, - "organisation": {
- "data": {
- "type": "organisations",
- "id": "ryqMcJn4b"
}
}
}
}
}
Delete Communication Setting
This endpoint allows a user to delete a communication setting.
Important: User role defines how they may use this endpoint:
- Only ADMIN users can delete organisation-level settings.
- For an account-level setting, both ADMINs and users with FULL access to the account can delete it.
200 response
Bad Request.
Unauthorized. The requested user does not have enough privilege.
Forbidden. This happens when an invalid api key is provided or the user does not have access to the api keys.
Not Found.
Internal Server Error
- 200
- 400
- 401
- 403
- 404
- 500
{- "meta": {
- "status": "deleted"
}
}
Get Communication Settings
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-"
}
}
}
}
]
}
query Parameters
Successful response.
Bad Request.
Unauthorized. The requested user does not have enough privilege.
Forbidden. This happens when an invalid api key is provided or the user does not have access to the api keys.
Unknown. This happens when parameter is unknown.
- 200
- 401
- 403
- 422
{- "data": [
- {
- "id": "communication:email-3JD1mkXfz",
- "attributes": {
- "created-by": "n6yTeW_lx",
- "created-date": 1565165403747,
- "is-account-level": false,
- "is-group-level": false,
- "is-organisation-level": true,
- "type": "communication",
- "enabled": true,
- "channel": "email",
- "filter": {
- "regions": "us-east-1",
- "services": [
- "EC2"
], - "ruleIds": [
- "S3-016"
], - "categories": [
- "security"
], - "riskLevels": [
- "HIGH"
], - "tags": [
- "tagName"
], - "filterTags": [
- "tagKey"
], - "compliances": [
- "AWAF"
]
}, - "configuration": {
- "users": [
- [
- "t-UoU9CsK"
]
]
}
}, - "type": "settings",
- "relationships": {
- "account": {
- "data": {
- "type": "accounts",
- "id": "H19NxM15-"
}
}, - "organisation": {
- "data": {
- "type": "organisations",
- "id": "ryqMcJn4b"
}
}
}
}
]
}
Create Communication Settings
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:
- 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.
- Each communication setting can be account-level OR organisation-level
- If creating account-level setting, you must have a valid
relationship.account
object. - If creating organisation-level settings you must set
relationship.account.data: null
- Only ADMIN users can create organisation-level settings.
- 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.
- If creating account-level setting, you must have a valid
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 |
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. |
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. |
Successful response.
Bad Request.
Unauthorized. The requesting user does not have enough privilege.
403 Forbidden
422 Unprocessable Entity
500 Internal Server Error
- Payload
{- "data": [
- {
- "type": "settings",
- "attributes": {
- "type": "communication",
- "enabled": true,
- "channel": "email",
- "filter": {
- "regions": "us-east-1",
- "services": [
- "EC2"
], - "ruleIds": [
- "S3-016"
], - "categories": [
- "security"
], - "riskLevels": [
- "HIGH"
], - "tags": [
- "tagName"
], - "filterTags": [
- "tagKey"
], - "compliances": [
- "AWAF"
]
}, - "configuration": {
- "users": [
- [
- "t-UoU9CsK"
]
]
}
}, - "relationships": {
- "account": {
- "data": {
- "type": "accounts",
- "id": "H19NxM15-"
}
}, - "organisation": {
- "data": {
- "type": "organisations",
- "id": "ryqMcJn4b"
}
}
}
}
]
}
- 200
- 401
- 403
- 422
- 500
[- {
- "data": {
- "id": "communication:email-3JD1mkXfz",
- "attributes": {
- "created-by": "n6yTeW_lx",
- "created-date": 1565165403747,
- "is-account-level": false,
- "is-group-level": false,
- "is-organisation-level": true,
- "type": "communication",
- "enabled": true,
- "channel": "email",
- "filter": {
- "regions": "us-east-1",
- "services": [
- "EC2"
], - "ruleIds": [
- "S3-016"
], - "categories": [
- "security"
], - "riskLevels": [
- "HIGH"
], - "tags": [
- "tagName"
], - "filterTags": [
- "tagKey"
], - "compliances": [
- "AWAF"
]
}, - "configuration": {
- "users": [
- [
- "t-UoU9CsK"
]
]
}
}, - "type": "settings",
- "relationships": {
- "account": {
- "data": {
- "type": "accounts",
- "id": "H19NxM15-"
}
}, - "organisation": {
- "data": {
- "type": "organisations",
- "id": "ryqMcJn4b"
}
}
}
}
}
]
Update Communication Settings
This endpoint allows you to update a specific communication setting.
IMPORTANT: User role defines how they may use this endpoint:
- Only ADMIN users can update organisation-level settings.
- 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 |
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-"
}
}
}
}
}
]
Successful response.
Bad Request.
Unauthorized. The requesting user does not have enough privilege.
403 Forbidden
422 Unprocessable Entity
500 Internal Server Error
- Payload
{- "type": "settings",
- "attributes": {
- "type": "communication",
- "enabled": true,
- "channel": "email",
- "filter": {
- "regions": "us-east-1",
- "services": [
- "EC2"
], - "ruleIds": [
- "S3-016"
], - "categories": [
- "security"
], - "riskLevels": [
- "HIGH"
], - "tags": [
- "tagName"
], - "filterTags": [
- "tagKey"
], - "compliances": [
- "AWAF"
]
}, - "configuration": {
- "users": [
- [
- "t-UoU9CsK"
]
]
}
}, - "relationships": {
- "account": {
- "data": {
- "type": "accounts",
- "id": "H19NxM15-"
}
}, - "organisation": {
- "data": {
- "type": "organisations",
- "id": "ryqMcJn4b"
}
}
}
}
- 200
- 401
- 403
- 422
- 500
[- {
- "data": {
- "id": "communication:email-3JD1mkXfz",
- "attributes": {
- "created-by": "n6yTeW_lx",
- "created-date": 1565165403747,
- "is-account-level": false,
- "is-group-level": false,
- "is-organisation-level": true,
- "type": "communication",
- "enabled": true,
- "channel": "email",
- "filter": {
- "regions": "us-east-1",
- "services": [
- "EC2"
], - "ruleIds": [
- "S3-016"
], - "categories": [
- "security"
], - "riskLevels": [
- "HIGH"
], - "tags": [
- "tagName"
], - "filterTags": [
- "tagKey"
], - "compliances": [
- "AWAF"
]
}, - "configuration": {
- "users": [
- [
- "t-UoU9CsK"
]
]
}
}, - "type": "settings",
- "relationships": {
- "account": {
- "data": {
- "type": "accounts",
- "id": "H19NxM15-"
}
}, - "organisation": {
- "data": {
- "type": "organisations",
- "id": "ryqMcJn4b"
}
}
}
}
}
]