View source for Data Posture API Tutorial

{{Box/start}}
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.
{{Box/end}}


{{Scenario|You’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 <nowiki>SAMPLE</nowiki> 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|'''Code Samples''']].

For more information on the API capabilities used in this tutorial, check out the [https://api.bigid.com/doc/dspm/ '''Data Posture API Docs'''].

== 1. Authenticate Using Your API Key ==

All API requests require authentication using a valid API key. Refer to [https://developer.bigid.com/wiki/BigID_API/API_Tutorial '''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''' <nowiki>/api/v1/actionable-insights/all-cases</nowiki>. 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:

{| class="wikitable"
! style="font-size:95%; color:#0e69b2; vertical-align:middle;" | '''Parameter''' 
! style="font-size:95%; color:#0e69b2; vertical-align:middle;" | '''Type''' 
! style="font-size:95%; color:#0e69b2; vertical-align:middle;" | '''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.

<html>
<iframe
  style="border:0px; width:100%; height:440px; border-radius:10px;"
  src='https://apiexplorer.bigid.tools/?url=actionable-insights%2Fall-cases&method=GET&headers=%5B%7B%22name%22%3A%22Authorization%22%2C%22value%22%3A%22SAMPLE%22%7D%5D'>
</iframe>
</html>

== 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:

{| class="wikitable"
! style="font-size:95%; color:#0e69b2; vertical-align:middle;" | '''BigID Field'''
! style="font-size:95%; color:#0e69b2; vertical-align:middle;" | '''Third-Party Field'''
|-
| '''caseLabel''' || Ticket title
|-
| '''policyName''' || Category or label
|-
| '''severityLevel''' || Priority
|-
| '''assignee''' || Assigned owner
|-
| '''dataSourceName''' || Affected resource
|}

== 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''' <nowiki>/api/v1/actionable-insights/cases:{actionType}</nowiki> endpoint. In order to use this endpoint, you should:
# In the request, tell BigID which field to update (in this case, caseStatus) and what the new value should be (set it to resolved).
# Add filters to select the cases you want to update, like policyName or caseStatus:open.
# 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:

<syntaxhighlight lang="json">
{
  "type": "CasesDB",
  "subType": "updateCases",
  "additionalProperties": {
    "field": "assignee",
    "newValue": "qaext@bigid.com",
    "casesFilters": [
      {
        "filterField": "policyName",
        "filterValues": [
          "policy1234"
        ]
      },
      {
        "filterField": "caseStatus",
        "filterValues": [
          "remediated"
        ]
      }
    ]
  }
}
</syntaxhighlight>

The following request uses the example request body above. To actually test this endpoint, replace the fields with real values based on the previous steps.

<html>
<iframe
  style="border:0px; width:100%; height:480px; border-radius:10px;"
  src='https://apiexplorer.bigid.tools/?url=actionable-insights%2Fcases%3Aresolve&method=POST&headers=%5B%7B%22name%22%3A%22Authorization%22%2C%22value%22%3A%22SAMPLE%22%7D%5D&selectedSetting=body&body=%7B%22type%22%3A%22CasesDB%22%2C%22subType%22%3A%22updateCases%22%2C%22additionalProperties%22%3A%7B%22field%22%3A%22assignee%22%2C%22newValue%22%3A%22qaext%40bigid.com%22%2C%22casesFilters%22%3A%5B%7B%22filterField%22%3A%22policyName%22%2C%22filterValues%22%3A%5B%22policy1234%22%5D%7D%2C%7B%22filterField%22%3A%22caseStatus%22%2C%22filterValues%22%3A%5B%22remediated%22%5D%7D%5D%7D%7D'>
</iframe>
</html>

If you only need to update the status of specific cases, this can be done using the '''PATCH''' <nowiki>/api/v1/actionable-insights/case-status/{caseId}</nowiki> endpoint. To do so:
# Replace {caseId} with the actual ID of the case you want to update.
# In the request body, set caseStatus to resolved.
# 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:

<syntaxhighlight lang="json">
{
  "caseStatus": "resolved",
  "auditReason": "Exported to Jira on July 14th"
}
</syntaxhighlight>

In the request below, the ''{caseId}'' is currently represented by a fake ID, 123abc. In order to test the endpoint, replace it with a case ID you have addressed in the previous steps.

<html>
<iframe
  style="border:0px; width:100%; height:420px; border-radius:10px;"
  src='https://apiexplorer.bigid.tools/?url=actionable-insights%2Fcase-status%2F123abc&method=POST&headers=%5B%7B%22name%22%3A%22Authorization%22%2C%22value%22%3A%22SAMPLE%22%7D%5D&selectedSetting=body&body=%7B%22caseStatus%22%3A%22resolved%22%2C%22auditReason%22%3A%22Exported%20to%20Jira%20on%20August%204%22%7D'>
</iframe>
</html>

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

{| class="wikitable"
! style="font-size:95%; color:#0e69b2; vertical-align:middle;" | '''Status Code'''
! style="font-size:95%; color:#0e69b2; vertical-align:middle;" | '''Example Response'''
! style="font-size:95%; color:#0e69b2; vertical-align:middle;" | '''What It Means'''
! style="font-size:95%; color:#0e69b2; vertical-align:middle;" | '''How to Fix It'''
|-
| '''200''' || Successful response with scan data || Everything’s looking good! || Keep cruising.
|-
| '''400''' || <code><nowiki>{ "error": "Scan ID is invalid" }</nowiki></code> || Bad or malformed scan ID provided || Double-check the scan ID you’re using.
|-
| '''404''' || <code><nowiki>{ "error": "Scan 1234 was not found" }</nowiki></code> || 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''' || <code><nowiki>{ "status": "error", "message": "Server error", "errors": [{}] }</nowiki></code> || BigID server hit a snag (internal error) || Wait a moment and retry. If it persists, reach out to support.
|}

== Code Samples ==
<tabs>
<tab name="Python"><syntaxhighlight lang="python" line>
# Data Posture API Tutorial

</syntaxhighlight></tab>
<tab name="JavaScript"><syntaxhighlight lang="javascript" line>

</syntaxhighlight>
</tab>
</tabs>

<html>
<style>
.tabs-tabbox > .tabs-container {
   margin-top: -1px;
   padding:
2px 6px;
   border-radius:
8px;
   position: relative;
   border:
2px solid #848484;
   width: inherit;
   max-width: inherit;
   min-width: inherit;
   box-shadow:
0px 4px 6px 1px rgba(0, 0, 0, 0.1);
   z-index: 1;
}

.tabs-tabbox > .tabs-label {
   margin:
0 3px;
   border-bottom:
none;
   border-radius:
4px 4px 0 0;
   position: relative;
   display: inline-block;
   vertical-align: bottom;
   padding-left: 10px;
   padding-right: 10px;
   padding-bottom: 3px;
   padding-top: 3px;
}

.tabs-tabbox > .tabs-input:checked + .tabs-label, .tabs-input-0:checked + .tabs-input-1 + .tabs-label {
   background-color: #0e69b2 !important;
   border-color:
#848484;
   z-index: 0;
   color: white;
}


.tabs-label {
   cursor: pointer;
   border:
2px solid #848484;
}

.mw-body .tabs-label {
   background-color: #ffffff26;
}
</style>
</html>

== 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.