NAV Navbar
java pyton


Welcome to the SDK documentation! enables a user to flag sensitive data on their database and then monitor user accesses to that data from within the application. Our SDK is used within your application's code to send information about these accesses to our API so your customers can view and analyze their users behaviour.


New users must create an account on our website. Our monitoring is applied to your Applications, which have one or more databases or services containing personal information.

Addding an Application

Step 1: The first step in on-boarding is to register your application on our dashboard by providing an Application name and Language. We understand that some applications are written in mutliple languages, so we ask that you provide most prominent backend language that performs the connection the your database. This helps us provide you with the correct SDK.

Identifying sensitive tables in your database

Step 2: We connect to your primary database to tag tables and columns which contain personal data. We only access the database schema, not the underlying data. From here, the user selects the tables that they would like to monitor for accesses. In order to identify the tables that contain sensitive data or personally identifiable information (PII), connects to your database and reads the table names and column names. This allows a user to select the tables and columns on their database that contains PII. does not store the login credentials or the any database information. Nor does access any data from within the database, we only access the database schema, not the database that stores real data.

Some clients may wish to create a view only user account and grant permissions to only access the information_schema from the database.

There are various options for securing a connection to your database, including IP whitelisting, SSL, SSH, PKI and Kerberos authenication. Blockbird data will work with you on the procedure that best meets your security requirements. Once the on-boarding process is complete, the network access can be closed as we do not connect to your database again, unless you wish to add or edit the mapping.

When connected to your database, we ask the user to select both the tables and columns that contain sensitive information. You can rename these attributes to make them more user friendly to non-technical team members. Upon completion, you will be given a Database Key and Database Secret which you will need when setting up the SDK to send data to

Database Key and Secret

Sending access information from your Application to

Once you have set up your account and mapped your sensitive tables, you must place some code in your application to communicate with our API.

Base URL

Adding the SDK to your codebase

  <!-- Blockbird data additions -->

Implementing the Blockbird SDK in your Application

Athenticate with blockbird.dataBlockbird API


// add Blockbird Audit
BlockbirdAudit bbAudit = BlockbirdAudit.getInstance(

Our API end-points are protected by a short-life ID Token that authenticates with each request. As part of the on-boarding, you will receive an Database Key and Database Secret which will be used to authenticate your requests. To authorize, you instantiate the BlockbirdAudit Object with the credentials that you received during onboarding.

SDK Parameters

Parameter Description
apiUrl the URL of the API
databaseKey the ID of your database on
databaseSecret your database Secret from

Data Access Queries

When a user accesses data on your application from your database, you can send this information to's API.

bbAudit.addQuery(user, group, table, columns, action, date, row_count)

To submit a query, you pass the following parameters to the method:

Parameter Required Type Description
user Yes String The unique ID of the user on your application
group Yes String The role(s) of the user on your application
table Yes String The Database Table in the query
columns Yes String[] The array of columns in the query
action Yes String Query peformed, one of CREATE, READ, UPDATE, DELETE
date Yes Date The time of the request
row_count Yes Number The number of rows returned, changed or deleted in the query

To reduce network traffic, queries are batched before sending to the API. If you wish to manually send the current batch at any time, you can call the run() method.;

This will send the current batch to's API.

Example of using SDK with Java Hibernate ORM

If your application uses the Hibernate framework to connect to your datebase, you can use an Interceptor to capture information on a users data accesses and send that information to our API. The EmptyInterceptor Object is an Abstract class that allows for application-defined custom interceptors. This object has a number of methods which can be capture informaion about the data that is being accessed or modified - these methods include onLoad(), onSave() and onDelete(). You can place the query submit function within these methods to capture data accesses and send them to our API.

Blockbird Data - System Architecture

System Architecture


Error Code Meaning
200 Success
400 Bad Request -- Your request sucks
401 Unauthorized -- Invalid Authorization header
404 Not Found -- The specified end-point was not found
500 Internal Server Error -- We had a problem with our server. Try again later.