Integrate the BeyondInsight API into Other Applications

You can integrate part of BeyondInsight's API into your applications using an API key.

The API Registration page is only available to BeyondInsight administrators.

The ID and key are generated by BeyondInsight.

  1. Select Configuration > General > API Registrations.
  2. Enter a name for the registration.
  3. Click Create New API Registration to create a new application registration.

BeyondInsight generates a unique identifier (API Key) that the calling application provides in the authorization header of the web request. The API Key is masked and can be shown in plain text by clicking the Show Key icon next to the Key field. The API Key can also be manually rotated, or changed, by clicking the circular arrow.

Once the key has been changed, any script using the old key receives a "401 unauthorized" error until the new key is used in its place. Read access and rotation of the key are audited.

  1. To configure a new registration or modify an existing one, select the registration, and then set the Authentication Rule Options.
    • Client Certificate Required: If enabled, a client certificate is required with the web request. If not, client certificates are ignored and do not need to be present. A valid client certificate is any client certificate signed by a certificate authority trusted by the server on which BeyondInsight resides.
    • User Password Required: If enabled, an additional authorization header value containing the RunAs user password is required with the web request. If not enabled, this header value does not need to be present and is ignored if provided. Square brackets surround the password in the header. 
      Authorization=PS-Auth key=c479a66f…c9484d; runas=doe-main\johndoe; pwd=[un1qu3];
    • Verify PSRUN Signature: The PSRUN signature is an extra level of authentication. It is computed from the factors using a shared secret between the client and server. PSRUN sends the signature as part of the header during its API request. If enabled, the server recomputes the signature during factor validation and compares it against the one sent by the client. If the signatures match, the client’s identity is considered verified. The signature effectively keeps the client in sync with the server. Changing the secret on the server requires the client to be rebuilt and guarantees that out-of-date clients cannot authenticate.
  2. On the Details page, click Add Authentication Rule to create authentication rules. At least one IP rule, PSRUN rule, valid source IP address (IPv4 or IPv6), IP range, or CIDR from which requests can be sent for this API Key is required. Enter one IP address, IP Range, or CIDR per line.

    X-Forwarded-For rules can also be created by providing a valid source IP address (IPv4 or IPv6), an IP range, or CIDR. In a load-balanced scenario, IP Authentication rules are used to validate the load balancer IP(s), and the X-Forwarded-For header is used to validate the originating client IP. Existing rules cannot be changed from an IP Rule to a X-Forwarded-For Rule or vice-versa. If an X-Forwarded-For rule is configured, it is required for the HTTP Request . If the X-Forwarded-For header is missing, the request fails with a 401 unauthorized error.

  3. Click Create Rule.