OpsCompass API Setup & First Time Use

Configuring access to the OpsCompass API will help you connect OpsCompass to your development workflow.

OpsCompass has introduced a new API to enable programmatic access to resource information. This guide will help you configure and begin to use the OpsCompass API.

This API allows authenticated access to resource information in the product. This article uses the new Resources interface to demonstrate how to connect and use the API.

Before you Begin

Here are the things you need to do before using the OpsCompass API

You must have an active user account, as a member of a company in OpsCompass to use the API. The OpsCompass administrator is responsible for adding new product users. API Access follows OpsCompass product roles – API requests follow the same permissions of the user. For example, if a user does not have access to OpsCompass Compliance module, the command
```
opscompass resources get-compliance
```
will return an 'unauthorized' result.
You must have access to a browser to authenticate to OpsCompass. API access is granted to users with a valid, active session. OpsCompass supports a Device Authorization module which permits redirection of authentication to permit logins where browsers are not available.

Authenticating to the OpsCompass API

All API requests are authenticated. Authentication is achieved by obtaining a Bearer token, which is provided to the API for use. The following parameters are required to authenticate to the OpsCompass API.

Authentication Domain:

auth.helm.opscompass.com

Audience:

https://opscompass-api.azure-api.net

Authentication is a two-step process:

Obtain the necessary device code by authenticating to OpsCompass via Authentication API Request.
Use the supplied device code to obtain a bearer token used to authorize API calls.

Authentication Example:

In Postman, the following example illustrates how to initiate authentication to the API:

Image of an API authentification

The request to OpsCompass is a POST request to the Authentication Domain. http://auth.helm/opscompass.com/device/code
In the request, BODY field, select x-www-form-urlencoded option to add the required request parameters.
client_id: Create the 'client_id' key, and add the supplied client ID into the value field. The Client ID must be obtained from OpsCompass directly.
audience: Create the audience key and add the value https://opscompass-api.azure-api.net.
scope: Create the scope key, and use 'offline_access' as a value if you intend to use the API over a period of time. By default, API access is provided for one day, with the opportunity to obtain refresh tokens to extend the duration of the session.

A successful request generates a result similar to below:

Image of code after a successful request

Submitting this request will generate a result with two important items:

device_code: make note of this device code. It is redeemed to obtain the bearer token in the next step.
verification_uri_complete: This is used to redeem the device code for the bearer token.

After obtaining the "Verification_uri_complete" URL, follow the link to authenticate to OpsCompass using two-factor authentication.

After authenticating to OpsCompass from the verification URI, you should see the following message:

Image of success message

The next step in the process is to redeem the device code obtained in step 1 for a bearer token. The bearer token will be used as the authorization for future API requests.

From Postman, create a new request.

Image of a new API request

The request to OpsCompass is a POST request to the Authentication Domain https://auth.helm.opscompass.com/oauth/token
In the request, BODY field, select x-www-form-urlencoded option to add the required request parameters.
grant_type: Create the grant_type key, using the value 'urn:ietf:params:oauth:grant-type:device_code'
device_code: Create the device_code key using the value provided in step 1.
client_id: Create the client ID key using the client ID from step 1.
Submit the request.

A successful request will return a bearer token for your use

Image of code token

After obtaining the "access token" (Bearer token), select it (without the quotation marks) and copy it to the clipboard. This token is required for future API requests from this device.

Calling the OpsCompass Resource API

After successful authorization, you are now ready to make requests to the OpsCompass Resource API. This API will provide basic resource configuration information, list drift (changes) for the requested resource, and list compliance problems for the requested resource.

Requests to OpsCompass API follow a basic pattern:

Base URL:

OpsCompass API uses a pattern for API Requests. Current and future APIs adhere to the following pattern:

https://opscompass-api.azure-api.net/fa-oc-api-[function scope]-prod/[function name]?[parameters]

Examples:

https://opscompass-api.azure-api.net/fa-oc-api-resources-prod/get-compliance?company=[your company name]&resourceId[your Cloud Resource ID]

https://opscompass-api.azure-api.net/fa-oc-api-resources-prod/get?company=[your company name]&resourceId=[your resource ID]

https://opscompass-api.azure-api.net/fa-oc-api-resources-prod/get-drift?company=[your company name]&resourceId=[your resource ID]

OpsCompass Resource API commands

get - this command returns a JSON description of the current resource configuration.
- Parameters
  - --company (Required) - this is the name of the OpsCompass company. Users may only request resources from companies to which they are authenticated and authorized.
  - --resourceId (Required, preferred) - this is the cloud-native resource identifier, such as an AWS ARN or Azure Resource ID. Note Azure resource IDs require the complete ID string, including the pathway.
  - --resource (Required if resourceID is not used) - rather than using the cloud-native resource ID, you may use the OpsCompass unique identifier. This can be found by viewing the resource in OpsCompass.
get-compliance - this command returns all current compliance violations for the requested resource.
- Parameters
  - --company (Required) - this is the name of the OpsCompass company. Users may only request resources from companies to which they are authenticated and authorized.
  - --resourceId (Required, preferred) - this is the cloud-native resource identifier, such as an AWS ARN or Azure Resource ID. Note Azure resource IDs require the complete ID string, including the pathway.
  - --resource (Required if resourceID is not used) - rather than using the cloud-native resource ID, you may use the OpsCompass unique identifier. This can be found by viewing the resource in OpsCompass.
  - --status (Optional) - filters request results to one or more statuses.
    - open (default when not specified) - returns only open compliance problems.
    - remediated - returns a history of remediated compliance issues
    - policy-exception - returns a list of compliance problems that have been granted an exception in OpsCompass
    - mitigation - returns a list of compliance problems that have been resolved with a mitigation in OpsCompass.
get-drift - this command returns all drift history for the requested resource.
- Parameters
  - --company (Required) - this is the name of the OpsCompass company. Users may only request resources from companies to which they are authenticated and authorized.
  - --resourceId (Required, preferred) - this is the cloud-native resource identifier, such as an AWS ARN or Azure Resource ID. Note Azure resource IDs require the complete ID string, including the pathway.
  - --resource (Required if resourceID is not used) - rather than using the cloud-native resource ID, you may use the OpsCompass unique identifier. This can be found by viewing the resource in OpsCompass.
  - --status (Optional) - filters request results to one or more statuses.
    - new - returns unacknowledged drift within the past 14 days.
    - inprogress - returns all unacknowledged drift
    - acknowledged - returns a list of drifts that have been acknowledged by a user previously.
    - resolved - returns a list of compliance-related drifts where changes reflect resolution to compliance problems.
  - --concern (Optional) - filters the request result to the specified drift concerns.