Skip to main content

Integrations

The Integrations API includes several methods allowing the third party integration management:

  • getHourlyUsageForAmazonEC2Instances: exposes the hourly usage for each Amazon instance category (micro, medium etc.).

  • configureAmazonEC2IntegrationUsingCrossAccountRole: configures the Amazon EC2 integration using the provided Amazon Resource Name of a valid AWS Cross-Account Role.

  • generateAmazonEC2ExternalIdForCrossAccountRole: generates the External ID required to configure the AWS Cross-Account Role.

  • getAmazonEC2ExternalIdForCrossAccountRole: returns the External ID required to configure the AWS Cross-Account Role.

  • disableAmazonEC2Integration: disables the previously configured Amazon EC2 integration.

  • getCompanyDetailsByAWSAccountId: retrieves information regarding the managed companies that have configured the Amazon EC2 integration with a specific AWS account.

API url: CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/integrations

getHourlyUsageForAmazonEC2Instances

This method exposes the hourly usage for each Amazon instance category (micro, medium etc.).

Parameters

Parameter

Type

Optional

Description

companyId

String

Yes

The ID of the company. The default value is the ID of the company linked to the user who generated the API key.

targetMonth

String

Yes

The month for which the usage is returned. The month will be provided in the following format: mm/yyyy. The default value is the current month.

Return value

This method returns an Object containing the hourly usage for each instance category.

Example

Request:

  {
       "params": {
           "targetMonth": "03/2015",
           "companyId": "55115935b1a43dcc4a7b23c6"
       },
       "jsonrpc": "2.0",
       "method": "getHourlyUsageForAmazonEC2Instances",
       "id": "5087eab8-b74f-4a3e-85b3-4271e85890d4"
  }  

Response:

  {
      "id": "5087eab8-b74f-4a3e-85b3-4271e85890d4",
      "jsonrpc": "2.0",
      "result": {
           "micro": 11,
           "medium": 157
       }
  }   

configureAmazonEC2IntegrationUsingCrossAccountRole

This method configures the Amazon EC2 integration using the provided Amazon Resource Name of a valid AWS Cross-Account Role.

For details regarding the integration steps, refer to this KB article.

Parameters

Parameter

Type

Optional

Description

crossAccountRoleArn

String

No

The Amazon Resource Name of a valid AWS Cross-Account Role.

companyId

String

Yes

The ID of the target company.

Default value: the ID of the company that the API key used to make the request belongs to.

integrationName

String

Yes

Enter a name to identify this specific integration.

Default value: the ID of the AWS account (awsAccountId).

Return value

This method always returns null.

Example

Request:

{
    "params": {
        "companyId": "55115935b1a43dcc4a7b23c6",
        "crossAccountRoleArn": "arn:aws:iam::111222345123:role/test",
        "integrationName": "integration1"
    },
    "jsonrpc": "2.0",
    "method": "configureAmazonEC2IntegrationUsingCrossAccountRole",
    "id": "5c6df60c-786a-4ea3-8ff3-b6e52b42aa46"
}

Response:

  {
      "id": "5c6df60c-786a-4ea3-8ff3-b6e52b42aa46",
      "jsonrpc": "2.0",
      "result": null
  }   

generateAmazonEC2ExternalIdForCrossAccountRole

This method generates an External ID. External IDs are required to configure AWS Cross-Account Roles, which you will need for Amazon EC2 integrations.

Once an integration has been performed, the External ID used is invalidated and permanently associated to that specific integration. To perform other integrations you will need to generate another External ID.

If the previous External ID has not been used, generating a new one will overwrite and invalidate it.

Tip

You can use the getAmazonEC2ExternalIdForCrossAccountRole method to retrieve the most recent External ID.

Parameters

Parameter

Type

Optional

Description

companyId

String

Yes

The ID of the target company. The default value is the ID of the company linked to the user who generated the API key.

No input parameters are required.

Return value

This method returns an String containing the generated External ID.

Attribute

Type

Details

result

String

The generated External ID.

Example

Request:

  {
       "params": {
           "companyId": "55115935b1a43dcc4a7b23c6"
       },
       "jsonrpc": "2.0",
       "method": "generateAmazonEC2ExternalIdForCrossAccountRole",
       "id": "5c6df60c-786a-4ea3-8ff3-b6e52b42aa46"
  }  

Response:

  {
      "id": "5c6df60c-786a-4ea3-8ff3-b6e52b42aa46",
      "jsonrpc": "2.0",
      "result": "5e93f474a30a2db85dd6046d6d5fg188"
  }  

getAmazonEC2ExternalIdForCrossAccountRole

This method returns the last External ID that was generated using the generateAmazonEC2ExternalIdForCrossAccountRole method.

Parameters

Parameter

Type

Optional

Description

companyId

String

Yes

The ID of the target company. The default value is the ID of the company linked to the user who generated the API key.

No input parameters are required.

Return value

This method will return a String containing information regarding the most recent External ID.

Attribute

String

Description

result

String

The value of the last External ID generated.

If the External ID was used for an integration, or was never generated, the method will return a null value.

Example

Request:

  {
       "params": {
           "companyId": "55115935b1a43dcc4a7b23c6"
       },
       "jsonrpc": "2.0",
       "method": "getAmazonEC2ExternalIdForCrossAccountRole",
       "id": "5c6df60c-786a-4ea3-8ff3-b6e52b42aa46"
  }  

Response:

  {
      "id": "5c6df60c-786a-4ea3-8ff3-b6e52b42aa46",
      "jsonrpc": "2.0",
      "result": "5e93f474a30a2db85dd6046d6d5fg188"
  }  

disableAmazonEC2Integration

This method disables a previously configured Amazon EC2 integration.

Parameters

Parameter

Type

Optional

Description

companyId

String

Yes

The ID of the company.

Default value: the ID of the company that the API key used to make the request belongs to.

integrationName

String

Yes

The name of the integration to be deleted.

Warning

If this parameter is not included in the request, all the integrations on the selected company will be deleted.

No input parameters are required.

Return value

This method does not return any value.

Example

Request:

  {
       "params": {
           "companyId": "55115935b1a43dcc4a7b23c6",
           "integrationName": "integration1"
       },
       "jsonrpc": "2.0",
       "method": "disableAmazonEC2Integration",
       "id": "97114e95-f36b-4206-bca0-6fb41bb47575"
  }  

Response:

  { 
      "id": "97114e95-f36b-4206-bca0-6fb41bb47575",
      "jsonrpc": "2.0",
      "result": null
  }   

getCompanyDetailsByAWSAccountId

This method retrieves information regarding the managed companies that have configured the Amazon EC2 integration with a specific AWS account.

Parameters

Parameter

Type

Optional

Description

accountId

String

No

The ID of the AWS account

Return value

This method returns an Array containing the companies that have the AWS integration configured with the specified AWS account. The size of the returned list is limited to 25 entries. Each entry has the following structure:

  • type - company type: 0 for Partner, 1 for Customer

  • name - the name of the company

  • id - the ID of the company

  • address - the physical address of the company

  • phone - the phone of the company

  • canBeManagedByAbove - the security management status for the company: true, if the security can be managed by parent companies

  • isSuspended - company account status: true, if the company is suspended

  • createdAt - a String representing the UTC date and time at which the company was created

  • country - a String representing the country code in ISO 3166 format. If the code is not specified, the String has the value N/A

  • state - a String representing the country state code in ISO 3166 format. If the code is not specified, the String has the value N/A

  • contactPerson - an Object containing the details of the contact person:

    • fullName, their first name and surname

    • email, their business email address

    • phoneNumber, their business phone number

    • companyRole, their position in the company

Example

Request:

  {
       "params": {
           "accountId": "123456789012"
       },
       "jsonrpc": "2.0",
       "method": "getCompanyDetailsByAWSAccountId",
       "id": "ae037403-7947-4f2b-b0b2-af190a8b44eb"
  }  

Response:

  {
      "id": "ae037403-7947-4f2b-b0b2-af190a8b44eb",
      "jsonrpc": "2.0",
      "result": [{
          "type": 1,
          "name": "Test customer",
          "id": "55191c7ab1a43d1f107b23c7", 
          "address": "Str Example No 1",
          "phone": "0040740000001",
          "canBeManagedByAbove": true,
          "isSuspended": false,
          "createdAt": "2017-02-21T15:02:54",
          "country": "CA",
          "state": "CA-BC",
          "contactPerson": {
              "fullName": "Stephen Jhonson",
              "email": "[email protected]",
              "phoneNumber": "0040740000001",
              "companyRole": "Owner / President"
          }
      },
       {
          "type": 0,
          "name": "Test partner",
          "id": "55191c5fb1a43da8107b23c6",
          "address": "Str Example No 2",
          "phone": "0040740000002",
          "canBeManagedByAbove": true,
          "isSuspended": false,
          "createdAt": "2017-01-28T15:01:15",
          "country": "CA",
          "state": "CA-BC",
          "contactPerson": {
              "fullName": "Stephen Jhonson",
              "email": "[email protected]",
              "phoneNumber": "0040740000001",
              "companyRole": "Owner / President"
          }
      }]
  }