BigID Developer Portal
BigID API/API Tutorial: Difference between revisions

BigID API/API Tutorial: Difference between revisions

From BigID Developer Portal
No edit summary
 
(28 intermediate revisions by 2 users not shown)
Line 15: Line 15:
There are two ways to authenticate ourselves to BigID:
There are two ways to authenticate ourselves to BigID:


* '''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.  
* '''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.  
* '''Username and Password''' - 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. This is a legacy authentication method and will only work for on-prem versions of BigID. [[BigID_API/User_Authentication|Details on this mechanism are here]]


In this tutorial, we're going to authenticate with BigID using Username/Password auth and retrieve a list of data sources.
== Token Authentication ==
{{:BigID_API/Token_Authentication}}


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>
[[Category:Tutorial]][[Category:API]]
<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%22bigid111%22%7D&selectedSetting=body"></iframe>
</html>
 
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.'''
 
<syntaxhighlight lang="JSON" line highlight="4">
{
    "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",
    ...
</syntaxhighlight>
 
== 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.
 
<html>
<iframe style="border:0px; width:100%; height:400px; border-radius:10px;" src="https://apibrowser.mybigid.com/?url=ds-connections&method=GET&selectedSetting=headers"></iframe>
</html>
 
In that API call, we can see a list of data sources and all the information for each data source.
 
<syntaxhighlight lang="JSON" lines>
{
    "status": "success",
    "statusCode": 200,
    "data": {
        "ds_connections": [
            "<data source info here>"
        ]
    }
}
</syntaxhighlight>
 
We now know the API calls we need and can use our programming language of choice to prepare our report. Below are some samples.
 
<tabs>
<tab name="NodeJS">
<syntaxhighlight lang="Javascript" lines>
import fetch from 'node-fetch';
 
let credentials = { username: "bigid", password: "bigid111" };
let env = "https://sandbox.mybigid.com/";
 
async function getDataSources(credentials, env) {
    // Request API Key using user/pass authentication
    const sessionRequest = fetch(env + 'api/v1/sessions', {
        method: 'POST',
        body: JSON.stringify(credentials),
        headers: { 'Content-Type': 'application/json' }
    });
    const sessionData = await request.json();
 
    const dsRequest = fetch(env + 'api/v1/ds-connections', {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': sessionData.auth_token
        }
    });
    return await dsRequest.json();
}
</syntaxhighlight>
</tab>
<tab name="Javascript">
<syntaxhighlight lang="JSON" lines>
let credentials = { username: "bigid", password: "bigid111" };
let env = "https://sandbox.mybigid.com/";
 
async function getDataSources(credentials, env) {
    // Request API Key using user/pass authentication
    const sessionRequest = window.fetch(env + 'api/v1/sessions', {
        method: 'POST',
        body: JSON.stringify(credentials),
        headers: { 'Content-Type': 'application/json' }
    });
    const sessionData = await request.json();
 
    const dsRequest = window.fetch(env + 'api/v1/ds-connections', {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': sessionData.auth_token
        }
    });
    return await dsRequest.json();
}
</syntaxhighlight>
</tab>
</tabs>

Latest revision as of 15:46, 21 August 2023

In this article, you'll learn:

  • How to get a BigID token using a REST API call
  • Where to find the BigID API documentation
  • How to use a BigID token to receive data from BigID


scenarioAs part of your data governance tasks, you need to get a list of data sources so you can be sure that your external data catalog has the right information. You've thought about doing this through the user interface, but you expect that you'll review this list around every three months. With that in mind, the BigID API seems like the best option. Discover and test the API calls you'll need to perform this task.

The BigID API allows you to perform all the actions you're used to performing via the BigID user interface programmatically. This is perfect for scenarios like the one in this exercise where you need to perform the same operation on a scheduled basis. In order to communicate with BigID over its API, we first need to authenticate ourselves.

Authenticating with BigID

There are two ways to authenticate ourselves to BigID:

  • 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.
  • Username and Password - 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. This is a legacy authentication method and will only work for on-prem versions of BigID. Details on this mechanism are here

Token Authentication

In this tutorial we're going to authenticate with BigID using a user token to retrieve a list of data sources.

First we'll need to create a user token for us to use through the BigID UI.

If you don't have access to a BigID environment to get a token, you can get one from the sandbox by running the automation after the steps.

Generate a Token

To do this we need to navigate to the Access Management screen under Administration -> Access Management. On the Access Management screen, select the user you want to create a token for from the System Users List. Then press the Generate button to start the token creation process.

Tokens can only be valid for up to 999 days. Since we're just using this token for testing, let's set it to 30 days and then click Generate like in the screenshot below.

On the next screen you'll see a name for the token as well as the token value. Copy the token value by clicking the icon to the right of it then close the dialog. You can't see the token value again so be sure you have saved it someplace safe.

Finally, save the user so the token can take effect.

Use the tool below to generate a token for the sandbox.

Exchange a token for an session token

Now that we have a user token, we need to exchange it for a system token that we can use to access API endpoints. This uses the /api/v1/refresh-access-token endpoint like below. Replace the TOKEN HERE in the request headers with your previously obtained user token and click Send to get a session token.

In response to this request you'll get the following: 

{
    "success": true,
    "systemToken": "eyJhbGciOi<don't copy me! I'm just an example!>..."
}

This session token can then get used on any BigID API.

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>"
         ]
    }
}
Retrieved from "https://developer.bigid.com/index.php?title=BigID_API/API_Tutorial&oldid=992"