Collibra REST API authentication

In this tutorial you will install Postman, an API Development Environment, and learn how to sign in and out of Collibra Data Governance Center as well as how to verify if your current session is authenticated.

Note   Almost all of the Collibra API calls require authentication.

Example   
curl -X POST \
  https://<your_dgc_environment_url>/rest/2.0/auth/sessions \
  -H 'Content-Type: application/json' \
  -d '{
	"username": "<user_name>",
	"password": "<password>"
}'

Postman

Note   If you prefer using another application, you can skip this step.

Note   Some references might be specific to the Postman application.

Although REST API calls do not necessarily require one specific program, and you can try them out directly from the Collibra API documentation, Postman can act as an HTTP client to send a request and receive a response.

To try API calls from the Collibra API documentation, go to https://<your_dgc_environment_url>/docs/index.html.

To install Postman:

  1. Download Postman corresponding to your operating system.
  2. Install the Postman application:
    • Windows:
      • Run the installer.
    • MacOS:
      • Unzip the application.
      • Move the application to the Applications folder.
    • Linux:
      • Unzip the application into your preferred folder.

For additional installation instructions, see the Postman documentation.

You can use Postman without an account. To do so, click the Skip signing in and take me straight to the app link at the bottom of the start-up screen.

Tip   Creating an account will allow you to access your call history and saved data across devices and in the web client.

For simple API operations there are a few areas that we will focus on:

Element

Name

Description

1

Method

A drop-down of API methods.

2

URL

The API call URL.

3

Params

The path parameters of the request.

4

Body

The body parameters of the request.

5

Code

A code generator for the request.

Calls in Postman

To make a call in Postman:

  1. Select the method
  2. Enter the URL
  3. Enter the required parameters
  4. Click Send.
Example   
GET https://<your_dgc_environment_url>/rest/2.0/application/info

You will see the response in the Response area, in the bottom half of the screen and the status code.

Tip   To learn more about status codes, hover the pointer over the status.

Authentication sessions and REST security

Collibra creates authentication sessions for all signed in users. You can configure the session idle timeout in section 14.7 of the Collibra DGC configuration in the Collibra Console. After the initial login, a JSESSIONID cookie is associated with the user. It is used to identify the user for the duration of the session.

Note   The out-of-the-box session idle timeout is 30 minutes in between API calls.

Depending on the REST security settings of the Collibra Data Governance Center you are connecting to, it may be required for you to provide additional information in the header of your request, such as a CSRF token or a referrer URL. A CSRF token is provided when you use the API Authentication resource.

Note   To configure REST security options, go to section 14.3 of the Collibra DGC configuration in Collibra Console

Collibra API authentication sessions

Example   
curl -X POST \
  https://<your_dgc_environment_url>/rest/2.0/auth/sessions \
  -H 'Content-Type: application/json' \
  -d '{
	"username": "<user_name>",
	"password": "<password>"
}'

To authenticate the user with a JSESSIONID cookie, create a session on the server and obtain a CSRF token, use the Authentication resource.

Example   
POST https://<your_dgc_environment_url>/rest/2.0/auth/sessions

You must provide the username and the password in a JSON body.

Example   
{
	"username": "...",
	"password": "..."
}

The response contains:

  • a CSRF token in JSON format in the response body.
  • Example   
    {
    	"csrfToken": "3d13555d-f5e5-460c-85f4-6707cd5a0af0"
    }
  • a Set-Cookie header which saves a JSESSIONID cookie.

Response codes:

Code Meaning
200 The current user has been authenticated.
401 The user name or password is wrong.

To check if the current user is authenticated, use the GET method and the/auth/sessions/current endpoint of the Authentication resource.

Example   
GET https://<your_dgc_environment_url>/rest/2.0/auth/sessions/current
curl -X GET \
  https://<your_dgc_environment_url>/rest/2.0/auth/sessions/current

Response codes:

Code Meaning
200 The current user is authenticated.
401 The current user is not authenticated.

To sign out the current user, use the DELETE method and the /auth/sessions/current endpoint of the Authentication resource.

Example   
DELETE https://<your_dgc_environment_url>/rest/2.0/auth/sessions/current
curl -X DELETE \
  https://<your_dgc_environment_url>/rest/2.0/auth/sessions/current

Response codes:

Code Meaning
204 The current user has been signed out.
401 The current user is not authenticated.

Basic authentication

You can use basic authentication to perform one-off API calls.

Note   This is not the recommended method of authentication. Use the Authentication resource instead.

In Postman:

  1. Go to the Authorization tab.
  2. From the Type drop-down menu, select Basic Auth.
  3. Enter the Username and Password.

Postman will automatically encode the values and create a header to include an Authorization key.

To pass this information inside your code include a header key Authorization with the value Basic <Base64_encoded_values>. The encoded values are <username>:<password>.

Example   
curl -H 'Authorization: Basic QWRtaW46YWRtaW4='

Next steps

Now that you can sign in and out of Collibra Data Governance Center, follow the next tutorial to learn how to create communities, domains, assets and how to add definitions via the Collibra REST API.

Additional resources