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 GraphQL 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 GraphQL Explorer, which 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 GraphQL explorer
To access the GraphQL 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.
While the Data Exporter role allows you to export data from the GraphQL 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.
infoWhile you can select the
conditions
attribute in the GraphQL 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 GraphQL explorer to retrieve different datasets, see the following articles:
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.
Applying Date Filters in the GraphQL Explorer
In the GraphQL Explorer, you can filter by date using a timestamp, the MM-DD-YYYY format, or Coordinated Universal Time (UTC). See the table below for examples.
Table 1. Supported Date Formats
Format | Description | Examples |
---|---|---|
Timestamp | A way of representing a specific point in time as a single number, usually the number of milliseconds since a fixed starting point called the "epoch." | 1751827200000 (September 6, 2025 in milliseconds since epoch) |
MM-DD-YYYY | A common way to represent dates in the United States. It stands for: MM = two-digit month (01–12) DD = two-digit day of the month (01–31) YYYY = four-digit year | 09-06-2025 09-6-2025 9-6-2025 |
UTC | A date-time string in ISO 8601 format that ends with the letter Z, which stands for "Zulu time" (another name for UTC time). For example, 2025-09-06 = date (YYYY-MM-DD) T = separator 00:00:00 = time (HH:MM:SS) Z = Zulu time (UTC) | 2025-09-06T00:00:00.000Z 2025-9-06T00:00:00.000Z 2025-9-6T00:00:00.000Z 2025-9-6T0:00:00.000Z 2025-9-6T0:0:00.000Z 2025-9-6T0:0:0.0Z 2025-9-6T0:0:0Z |
In addition, you can use relative date expressions in your filters, as shown in the following table.
Table 2. Supported Relative Date Expressions
Expression | Description |
---|---|
now | Current date and time |
today | Current date and time |
yesterday | Yesterday at current date and time |
-3m | Current time minus three minutes (three minutes in the past) |
+3m | Current time plus three minutes (three minutes in the future) |
-2h | Current date and time minus 2 hours |
+1h | Current date and time plus 1 hour |
-5d | Current date and time minus 5 days |
+7d | Current date and time plus 7 days |
-3w | Current date and time minus three weeks |
+3w | Current date and time plus three weeks |
-6M | Current date and time minus 6 months |
+1M | Current date and time plus 1 month |
-2y | Current date and time minus two years |
+2y | Current date and time plus two years |
Lastly, you can use date operators with attributes of type Date, DateTime, Time, or with calculated attributes that return these types. Both absolute and relative dates are supported. The following table summarizes the date operators available for GraphQL queries.
Table 3. Supported Date Operators
Operator | Syntax | Examples |
---|---|---|
Before | BEFORE date | dateCreated BEFORE yesterday , lastUpdated BEFORE 09-06-2025 |
Between | BETWEEN [date1, date2] | dateCreated BETWEEN [-2d, now] , firstFound BETWEEN [01-01-2025, 01-31-2025T23:59:59.999Z] |
In Last | IN_LAST relative-date | dateCreated IN_LAST 3d (e.g.: hosts created in the last 3 days) |
In Next | IN_NEXT relative-date | dueDate IN_NEXT 1M (e.g.: tickets dued in the next month) |
Is | IS date | lastUpdated IS 09-06-2025T23:59:59.999Z |
Not Between | NOT_BETWEEN [date1, date2] | firstFound NOT_BETWEEN [01-01-2025, 01-31-2025T23:59:59.999Z] |
Not In Last | NOT_IN_LAST relative-date | dateCreated NOT_IN_LAST 1d (e.g.: vulnerabilities not created in the last day) |
Not In Next | NOT_IN_NEXT relative-date | due_date NOT_IN_NEXT 3h (e.g.: tickets not dued in the next 3 hours) |
Not Is | NOT_IS date | lastUpdated NOT_IS 09-06-2025T23:59:59.999Z |
Since | SINCE date | lastUpdate SINCE 1523544660507 |
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 'X-Requested-With: XMLHttpRequest' \
--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 'X-Requested-With: XMLHttpRequest' \
--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 "X-Requested-With: XMLHttpRequest" \
-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 |