Overview

An Application Programming Interface (API) is an interface that software uses to access data, server software, or other applications. It is a software intermediary that allows two applications to talk to each other. APIs communicate through a set of rules that define how computers, applications, or machines can talk to each other. In other words, an API is the messenger that delivers your request to the provider that you're requesting it from and then delivers the response back to you.


The API makes use of standard HTTP methods (GET\POST) to perform the same actions that are available in the Web console UI using dedicated endpoints. To authenticate with an API, you need an API key.


An API key is a unique identifier used to authenticate a user. An API key can act as a secret authentication token as well as a unique identifier. Your beSECURE API key will match your user account rights and you will receive a pre-configured account (login), as well as a personalized API key tied to that account which uses the same permissions.


Generating an API key in beSECURE

To generate an API key in beSECURE, do the following:

  1. Log in to beSECURE.
  2. In the upper-left corner of the Home page, select DevOps.
  3. Select Admin > Accounts > List.
  4. Select the account you want to create an API for.
  5. Select the API Key tab.
  6. Click inside the API Key box to generate the key.


Examples of using APIs

Creating a new user account

  1. Go to https://besecure-api.beyondsecurity.com/?version=latest.
  2. From the Language menu at the top of the beSECURE API Documentation page, select your desired coding language (this example uses PowerShell).
  3. Copy the code.
  4. Open your coding interface.
  5. Replace the following mandatory fields:
    1. {{apikey}} - Your beSECURE API key.
    2. {{username}} - The user's name that you want to create.
    3. {{password}} {{password_retype}} - The password that will correspond with the username (it must be at least eight characters in length).
    4. {{securityprofile}}- The security profile ID to use with this user account.
      1. To get the security profile ID in beSECURE: From the Home page, select Admin > Accounts > Security Profile. Select the desired security profile to see its ID.
    5. {{userprofile}}- An account profile ID, to use with this user account (scanning, reporting, administrator).
      1. To get the account profile ID in beSECURE: From the Home page, select Admin > Accounts > Account Profile. Select the desired account profile to see its ID.
    6. {{language}} - The language to use. Enter single-digit numeric value of one of the following options: 1=Japanese 2=English 3=Chinese 4=Korean 5=French 6=Traditional Chinese.
    7. {{timezone}} - Continent/City (case sensitive).
    8. {{contact}}- The contact ID to be use with this user account.
      1. To get the contact ID in beSECURE: From the Home page, select Admin > Accounts > Contacts. Select the desired contact to see its ID.
    9. {{hostname}} - The beSECURE server's IP address or FQDN.

      PowerShell example:beSECURE UI example:


Creating a new Contact

  1. Go to https://besecure-api.beyondsecurity.com/?version=latest.
  2. From the Language menu at the top of the beSECURE API Documentation page, select your desired coding language (this example uses PowerShell).
  3. Copy the code.
  4. Open your coding interface.
  5. Replace the following mandatory fields (you can add information for fields not listed, if desired):
    1. {{apikey}} - Your beSECURE API key.
    2. {{contact_name}} -The new contact’s name.
    3. {{hostname}} - The beSECURE server's IP address or FQDN.

      PowerShell example:
      Note: The Country option is from a list. To use this field, enter the country's full name.

      beSECURE UI example:


Creating a scan

  1. Go to https://besecure-api.beyondsecurity.com/?version=latest.
  2. From the Language menu at the top of the beSECURE API Documentation page, select your desired coding language (this example uses PowerShell).
  3. Copy the code.
  4. Open your coding interface.
  5. Replace the following mandatory fields:
    1. {{apikey}} - Your beSECURE API key.
    2. {{network_name}} - The name of your scan.
    3. {{network_scanner}} - The LSS ID of your scanner.
      1. To get the LSS ID in beSECURE: From the Home page, select Admin > Deployment> LSS. Select the desired LSS to see its ID.
        Note: The LSS ID is not the same as your server ID.
    4. {{network_parent}}- Your beSECURE organization ID.
      1. To get the organization ID in beSECURE: From the Home page, select Admin > Organization > List. Select the desired organization to see its ID.
    5. {{network_range}} - Domain name, IP range, or a single IP (separated with a comma).
    6. notifications_scanstarted = yes/no.
    7. notificatios_scancompleted = yes/no.
    8. notifications_scanchanges = yes/no.
    9. {{contact}}- The ID of the beSECURE contact that will receive information about the scan.
      1. To get the contact ID in beSECURE: From the Home page, select Admin > Accounts> Contacts. Select the desired contact to see its ID.
    10. report_customization_format = pdf/xml.
    11. &report_customization_type = complete/filtered/differential.
    12. Make sure to replace {{hostname}} with your computer's DNS/IP address (example: cloud2.beyondsecurity.com) for an IP address (remove the https://).
      PowerShell example:
      beSECURE UI example: