Introduction

By configuring an IBM Cloud™ Security Advisor notification channel, you can be alerted to any reported vulnerabilities as soon as the report is available. With a process in place for handling alerts, you can ensure that you're in compliance and prepared if or when there is an issue. You're able to immediately start an investigation into any reported issue and fix the vulnerability before it becomes a larger problem in your application. For example, some compliance standards require that issues must be responded to and closed within 24 hours, and the response is audited. With Security Advisor alerts in place, you are notified and can start resolving issues immediately.

API endpoint

https://{region}.secadvisor.cloud.ibm.com/notifications/

Replace {region} with the prefix that represents the geographic area where your Security Advisor service instance resides. Currently, the us-south and eu-gb regions are supported.

Authentication

This API is protected by IBM Cloud Identity and Access Management. You must also provide your account ID to authenticate your requests, you must provide your IBM Cloud account ID and an IBM Cloud Identity and Access Management IAM token. Your account ID can be found in your dashboard by clicking Manage > Account > Account settings. To obtain an IAM token, you can use the following steps.

  1. In the IBM Cloud dashboard, click Manage > Access (IAM).
  2. Select IBM Cloud API keys.
  3. Click Create an IBM Cloud API key
  4. Give your key a name and describe it. Click Create. A screen displays with your key.
  5. Click Copy or Download your key. When you close the screen, you can no longer access the key.
  6. Make the following cURL request with the API key that you created.

    curl -k -X POST \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --header "Accept: application/json" \
     --data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
     --data-urlencode "apikey={apikey}" \
     "https://iam.cloud.ibm.com/identity/token"
    

For more information, see the IAM documentation.

Error handling

The IBM Cloud™ Security Advisor service uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Status code summary
Status code Description
200 OK Everything worked as expected.
201 OK Everything worked as expected. No content
400 Bad Request The request was unsuccessful, often due to a missing required parameter.
401 Unauthorized The parameters were valid but the request failed due insufficient permissions.
404 Not Found The requested resource doesn't exist.
410 Gone The requested resource was deleted and no longer exists.
429 Too Many Requests Too many requests hit the API too quickly.
500 Server Error Something went wrong on Security Advisor's end.

Methods

List all channels

List all of the channels in the account.

GET /v1/{account_id}/notifications/channels
Request

Custom Headers

  • An Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

Query Parameters

  • Limit the number of the returned documents to a specified number.

  • The number of the item from which you want to start returning data. The default is 0.

Response

Status Code

  • OK

Example responses

Create a channel

Create a notification channel.

POST /v1/{account_id}/notifications/channels
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

Body for query findings

Response

Status Code

  • OK

Example responses

Delete channels

Delete one or more your configured channels at the same time.

DELETE /v1/{account_id}/notifications/channels
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

Body for bulk delete notification channels. You can specify one or more channel IDs to be deleted.

Response

Status Code

  • OK

  • An unexpected error occurred. Wait a few minutes and try again.

Example responses

Delete a channel

Delete a specific channel and its configuration.

DELETE /v1/{account_id}/notifications/channels/{channel_id}
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

  • Channel ID

Response

Status Code

  • OK

  • Unexpected error.

Example responses

View a specific channel

Get the details of a specific channel.

GET /v1/{account_id}/notifications/channels/{channel_id}
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

  • Channel ID

Response

Status Code

  • OK

  • Unexpected error.

Example responses

Update a channel

Update a notification channel.

PUT /v1/{account_id}/notifications/channels/{channel_id}
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

  • Channel ID

Body for update notification channel

Response

Status Code

  • OK

Example responses

Test a channel

Test a notification channel that is configured for account.

GET /v1/{account_id}/notifications/channels/{channel_id}/test
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

  • Channel ID

Response

Status Code

  • OK

Example responses

Fetch public key

Fetch a public key that you can use to decrypt messages in the notification payload.

GET /v1/{account_id}/notifications/public_key
Request

Custom Headers

  • The Identity & Access Management (IAM) Bearer token.

Path Parameters

  • Account ID

Response

Status Code

  • OK

No Sample Response

This method does not specify any sample responses.