Brinqa Platform API

This article provides instructions on authenticating with the Brinqa Platform application programming interface (API) and how to run queries using the built-in GraphiQL Explorer.

Overview

The Brinqa Platform API allows for flexible interactions with the Brinqa Platform, offering a powerful way to extract and manipulate your data to better serve your needs. It uses GraphQL as the query language to interact with the Brinqa Platform API, providing an efficient and performance-friendly method to specify and retrieve the exact data you need.

GraphQL allows you to specify exactly what data you need and receive that data in a single request. To make it even easier to work with, Brinqa includes a GraphiQL Explorer. GraphiQL is an in-browser integrated development environment (IDE) for writing, validating, and testing GraphQL queries. You can use this tool to explore the objects made available by the Brinqa API and build your queries with just a few clicks.

How to use the GraphiQL explorer

To access the GraphiQL Explorer, you must log in to your Brinqa Platform as a Data Exporter or System Administrator. After you've logged in, navigate to Administration > System > GraphQL Explorer.

note

While the Data Exporter role allows you to export data from the GraphiQL Explorer, you must have additional roles that provide permissions to access the data, such as Administrator, Remediation owner, or Risk owner. For additional information on role permissions, please see the Roles documentation.

You can type your query directly or use the icons on the left-hand side to access various explorers for additional assistance. The IDE consists of three panes:

• Left pane: Displays different content based on which icon you've selected:

  • : Displays the schema of each object.

  • : Displays the history of your executed queries.

  • : Displays the cURL command of your query.

  • : Displays the list of objects and fields that you can use to build your query.

    info

    While you can select the conditions attribute in the GraphiQL Explorer, it is currently not supported. Please use other filtering options to refine your queries.

• Middle pane: Displays the query formed automatically after you've selected the fields.

• Right pane: Displays the result after you've executed the query.

For specific examples of how to use the GraphiQL explorer to retrieve different datasets, see the following articles:

• Retrieve active assets

• Retrieve new findings

• Query for active and public hosts

• Filter for open and assigned tickets

• Retrieve critical vulnerability details

Important

GraphQL is specifically designed for querying less than 5,000 datasets and is not intended for bulk exports or as a bulk API. Typical usage should involve queries designed to display between 100 to 200 entries. For bulk data exports, please utilize Brinqa Connect.

Obtain an API token

Before you can use the Brinqa Platform API, you need to authenticate your requests. The Brinqa Platform API uses bearer token authentication to verify the identity of the user making the request. To interact with the API and perform operations such as running queries or retrieving data, you must first obtain an access token.

To get your access token, use the following cURL command:

curl --location --request POST 'https://<your-brinqa-platform-url>/api/auth/login' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "<your-username>",
    "password": "<your-password>"
}'

In this command, replace <your-brinqa-platform-url>, <your-username>, and <your-password> with your Brinqa Platform URL and login information. This token grants the same permissions as the user's access within the Brinqa Platform. If a user's access in the Brinqa Platform is limited to a certain subset of data, their API access will also be limited to that subset.

<your-password> is the password assigned to the user record in the Brinqa Platform. In case your user is configured with single sign-on (SSO) authentication, you can edit the user record and set a password specifically for token generation. Alternatively, you can create a new user designated to generate tokens. Either way, your SSO username and password remain unaffected.

If you have multi-factor authentication (MFA) enabled, add this line at the end of the cURL command: "code": "<your-mfa-code>". So the full cURL command would read:

curl --location --request POST 'https://<your-brinqa-platform-url>/api/auth/login' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "username": "<your-username>",
    "password": "<your-password>",
    "code": "<your-mfa-code>"
},

In this command, replace <your-mfa-code> with the authenticator code generated by your organization's authenticator app.

Upon successful authentication, you will receive a response similar to the following that includes your access token:

{
    "username": "<your-username>",
    "token_type": "Bearer",
    "access_token": "<your-access-token>",
    "expires_in": 86400,
    "refresh_token": ""
}

Copy <your-access-token> value. This token is what you will use to authenticate your requests when you execute queries.

Execute Brinqa API queries

After obtaining the access token from the auth/login endpoint, insert it into your cURL command like so:

curl 'https://<your-brinqa-platform-url>/graphql/caasm' \
--compressed \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-access-token>" \
-H "Accept: application/json" \
-H "Accept-Encoding: gzip, deflate" \
--data '{ 
  "query": "query MyQuery {  assets(filter: "status=active", limit: 5) {    complianceStatus    displayName    firstSeen    id    lastUpdated    status  }}",
  "variables": null,
  "operationName": "MyQuery"
}'

The access token is valid for 86400 seconds, or 24 hours. After it expires, you can generate a new token by following the same step.

Error code descriptions

Here are some common error codes and their meanings that you might encounter while working with the Brinqa Platform API:

Error Code or Problem	Suggestion
401 Unauthorized	The access token has expired
403 Forbidden	The user doesn't have permissions to access that endpoint
404 Not Found	May mean that the data Model was incorrectly specified
405 Not Acceptable	May mean that a parameter was incorrect. Check for a message in the response.
Response comes back with HTML	The URI may be missing the /api component