Data Posture API Tutorial

In this article, you'll learn:

• How to retrieve security issues from the Data Posture API.
• How to export relevant issues to a third-party system.
• How to use the Apply Action API to update multiple issues at once.
• How to mark issues as resolved after export to keep BigID in sync.

scenarioYou’re part of the security team managing your organization’s data security posture. Each week, BigID identifies new issues like exposed sensitive data or misconfigurations. Your team handles remediation in a third-party system like Jira or ServiceNow, so you need a way to export these issues from BigID, assign them for follow-up, and mark them as resolved to keep your backlog clean and accurate.

In this tutorial, we'll use SAMPLE as our session token. This is unique to the training sandbox and will not work in other environments. See BigID API/Tutorial for information on authenticating with BigID.

To view the complete code for all steps, see the section labelled Code Samples.

For more information on the API capabilities used in this tutorial, check out the Data Posture API Docs.

1. Authenticate Using Your API Key

All API requests require authentication using a valid API key. Refer to BigID Documentation to obtain your token. Then, define the Authorization header using the format Authorization: Bearer YOUR_API_KEY. This header must be included in every request to ensure proper authentication and access to BigID’s API endpoints. Throughout the tutorial, we will be using SAMPLE as our token.

2. Retrieve Security Issues

There are multiple endpoints available for fetching security cases, but because our goal is to export these issues to a third party system, we want to use the GET /api/v1/actionable-insights/all-cases. This will allow us to fetch all existing security issues, as well as limit the selection based on various parameters if necessary.

In the case that you do not want to fetch all cases, you can filter the response based on several parameters, all of which are outlined in the following table:

Parameter	Type	Description
skip	integer	Number of records to skip (for pagination)
limit	integer	Number of records to return
filter	string	BigID Query Language filter to narrow results
fields	string	Comma-separated list of fields to return
sort	string	Field to sort by, plus optional ASC/DESC
requireTotalCount	boolean	Whether to include totalCount in response

Once you have fetched the details for all of the security cases you are interested in, you can proceed to the next step.

3. Export Issues to Your Third-Party System

Once you retrieve the list of open security issues, the next step is to export them to your third-party system for remediation. This could be a ticketing platform like Jira, ServiceNow, or a SOAR tool for automated workflows.

For each issue, map the relevant fields to your third-party system’s API. Common mappings might include:

BigID Field	Third-Party Field
`caseLabel`	Ticket title
`policyName`	Category or label
`severityLevel`	Priority
`assignee`	Assigned owner
`dataSourceName`	Affected resource

[ maybe more on this? ]

4. Mark Issues as Resolved

After successfully exporting the issues, you’ll want to mark them as resolved in BigID to avoid duplicate work and keep the backlog clean. You have two options for marking issues as resolved using the API.

First, you can do so in bulk using the PATCH /api/v1/actionable-insights/cases:{actionType} endpoint. In order to use this endpoint, you should:

1. In the request, tell BigID which field to update (in this case, caseStatus) and what the new value should be (set it to resolved).
2. Add filters to select the cases you want to update, like policyName or caseStatus:open.
3. Run the request. BigID will return the list of case IDs that were successfully updated.

For example, your request may be structured like the following:

[ insert example ]

If you only need to update the status of specific cases, this can be done using the PATCH /api/v1/actionable-insights/case-status/{caseId} endpoint. To do so:

1. Replace {caseId} with the actual ID of the case you want to update.
2. In the request body, set caseStatus to resolved.
3. Add an auditReason so your team knows why the change was made (for example, “Exported to Jira on July 14th”).

For example, your request may be structured like the following:

[ insert example ]

5. Troubleshooting

If your request fails, here’s what the server might tell you, and how to fix it:

Status Code	Example Response	What It Means	How to Fix It
200	Successful response with scan data	Everything’s looking good!	Keep cruising.
400	{ "error": "Scan ID is invalid" }	Bad or malformed scan ID provided	Double-check the scan ID you’re using.
404	{ "error": "Scan 1234 was not found" }	Scan ID doesn’t exist	Make sure the ID is valid and fetched from the parent scans endpoint.
401	Unauthorized	API key missing or invalid	Verify your API key and authorization header.
500	{ "status": "error", "message": "Server error", "errors": [{}] }	BigID server hit a snag (internal error)	Wait a moment and retry. If it persists, reach out to support.

Summary

Congratulations! In this tutorial, you have learned how to retrieve open security issues from BigID, export those issues to a third-party system for remediation, and mark the issues as resolved in BigID to keep your backlog clean and accurate. By following these steps, you can streamline your remediation process, reduce manual effort, and maintain a clear, up-to-date view of your organization’s security posture.