Skip to main content

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 System Administrator. After you've logged in, navigate to Administration admin button > System > GraphQL Explorer.

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:

    • GraphiQL Documentation Explorer icon: Displays the schema of each object.

    • GraphiQL History icon: Displays the history of your executed queries.

    • GraphiQL Code Exporter icon: Displays the cURL command of your query.

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

  • 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 data sets, see the following articles:

Important

GraphQL is specifically designed for querying less than 5,000 data sets 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 ProblemSuggestion
401 UnauthorizedThe access token has expired
403 ForbiddenThe user doesn't have permissions to access that endpoint
404 Not FoundMay mean that the data Model was incorrectly specified
405 Not AcceptableMay mean that a parameter was incorrect. Check for a message in the response.
Response comes back with HTMLThe URI may be missing the /api component