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 Intelligence Platform as well as how to verify if your current session is authenticated.
Almost all of the Collibra API calls require authentication.
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
If you prefer using another application, you can skip this step.
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:
- Download Postman corresponding to your operating system.
- 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.
- Windows:
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.
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:
- Select the method
- Enter the URL
- Enter the required parameters
- Click Send.
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.
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 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.
The packaged session idle timeout is 30 minutes in between API calls.
Depending on the REST security settings of the Collibra Data Intelligence Platform 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.
To configure REST security options, go to section 14.3 of the Collibra configuration in Collibra Console
Collibra API authentication sessions
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.
POST https://<your_dgc_environment_url>/rest/2.0/auth/sessions
You must provide the username and the password in a JSON body.
{
"username": "...",
"password": "..."
}
The response contains:
- a CSRF token in JSON format in the response body.
- a Set-Cookie header which saves a JSESSIONID cookie.
{
"csrfToken": "3d13555d-f5e5-460c-85f4-6707cd5a0af0"
}
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.
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.
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.
This is not the recommended method of authentication. Use the Authentication resource instead.
In Postman:
- Go to the Authorization tab.
- From the Type drop-down menu, select Basic Auth.
- 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>
.
curl -H 'Authorization: Basic QWRtaW46YWRtaW4='
Next steps
Now that you can sign in and out of Collibra Data Intelligence Platform, follow the next tutorial to learn how to create communities, domains, assets and how to add definitions via the Collibra REST API.
Additional resources
- Consult the REST API documentation provided with your version of Collibra Data Intelligence Platform at https://<your_collibra_url>/docs/index.html.
- Read the Collibra JSON Web Token authentication guide.
- Read the Collibra REST API authentication with JSON Web Token tutorial.
- Read the Collibra Platform Configuration section of the documentation.