BigID API/Add Data Source Tutorial: Difference between revisions

From BigID Developer Portal
No edit summary
Line 11: Line 11:
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.
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.


== Authenticating with BigID ==
== Discovering Data Sources ==


There are two ways to authenticate ourselves to BigID:
You can see what data source connectors are installed in your environment through the BigID UI, but since we're focused on the API (and because all actions in the UI can be performed in the API, we are going to use the API to retrieve them.
 
* '''Username and Password''' - This is the easiest way to authenticate to BigID. You provide a username and password to the /sessions endpoint and BigID will return a session token that is valid for any other API endpoints (given that user has permissions to access them) for 24 hours.
* '''User Token''' - A user token (generated from Administration -> Access Management by a System Administrator) allows you to access BigID by exchanging a user token for a session token at the /refresh endpoint. This means you don't have to store your username and password within an application, but user tokens are only valid for a maximum of 999 days.
 
In this tutorial, we're going to authenticate with BigID using Username/Password auth and retrieve a list of data sources.


Below you'll see the POST request we'll use to authenticate. The body of the request contains our username and password and we're directing the request to the sessions endpoint in our BigID Sandbox system. Press {{Key|Send}} to get a session token.
Below you'll see the POST request we'll use to authenticate. The body of the request contains our username and password and we're directing the request to the sessions endpoint in our BigID Sandbox system. Press {{Key|Send}} to get a session token.


<html>
<html>
<iframe style="border:0px; width:100%; height:400px; border-radius:10px;" src="https://apibrowser.mybigid.com/?url=sessions&method=POST&body=%7B%22username%22%3A%22bigid%22%2C%22password%22%3A%22learner%22%7D&selectedSetting=body"></iframe>
<iframe style="border:0px; width:100%; height:400px; border-radius:10px;" src='https://apibrowser.mybigid.com/?url=sessions&method=GET&headers=%5B%7B%22name%22%3A%22Authorization%22%2C%22value%22%3A%22SAMPLE%22%7D%5D'></iframe>
</html>
</html>



Revision as of 19:45, 27 October 2021

In this article, you'll learn:

  • How to list available data source connectors within a system
  • Where to find parameters required for a given data source
  • How to add a data source using the BigID API


scenarioYou have a custom system that maintains an inventory of your databases and have just purchased BigID to better understand what's inside those databases for an internal AI initiative. Your executive staff says this will "bring your organization into the modern age". Use the BigID API to add a data source to start your integration with the inventory system.

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.

Discovering Data Sources

You can see what data source connectors are installed in your environment through the BigID UI, but since we're focused on the API (and because all actions in the UI can be performed in the API, we are going to use the API to retrieve them.

Below you'll see the POST request we'll use to authenticate. The body of the request contains our username and password and we're directing the request to the sessions endpoint in our BigID Sandbox system. Press Send to get a session token.

In the response, there's a bunch of information about the logged in user. For our purposes, we just care about line 4, the auth_token. This token is what we'll use the authenticate with the other BigID APIs. We've placed a sample below with the auth token highlighted. Copy the auth token from the request you placed above. We'll need it in just a second.

{
    "success": true,
    "message": "Enjoy your token!",
    "auth_token": "eyJhbGciOiJ<don't copy me! I'm just an example!>...",
    "username": "bigid",
    "firstName": "BigID Admin",
    "permissions": [
        "admin",
        "permission.tasks.edit",
        "permission.tasks.read_task_list",
    ...

Calling an API

Now that you have a session token we can directly call BigID APIs. Documentation for these APIs is available at https://www.docs.bigid.com/bigid/reference/api-getting-started . Since we're just trying to perform a simple task, we don't need the docs here, just to know that GET /ds-connections is the endpoint to retrieve a list of data source connections.

Add a new header named "Authorization" and paste the session token you got in the previous request to authenticate yourself.

In that API call, we can see a list of data sources and all the information for each data source.

{
    "status": "success",
    "statusCode": 200,
    "data": {
        "ds_connections": [
            "<data source info here>"
         ]
    }
}