API authentication

In this article:

• Bearer authentication

• Get the bearer token

• Authenticate an API request with a bearer token

• Error codes related to authentication & authorization

• Client secret authentication

Bearer authentication

To work with the DataClarity API, you must authenticate the requests with Bearer Authentication. Bearer authentication is an HTTP authentication scheme involving security bearer tokens. The bearer token is a cryptic string generated by the authentication server in response to a login request. Then, the client needs to send this bearer token in the Authorization header when making requests to the DataClarity resources:

Authorization: Bearer {bearer-token}

Access tokens provide authentication for the requester and contain permissions of how the authenticated user can use the DataClarity’s API. Users who call REST API methods must have corresponding permissions to perform the task represented by each method that they want to call.

Access tokens expire after some time (30 minutes by default) and require a user to log in again.

Get the bearer token

The client can get a user’s bearer token by sending the following API request to the authentication engine:

POST {server}/auth/realms/{tenant}/protocol/openid-connect/token

Request body

The request body contains the following details.

Key	Value
client_id	Set as dc-ui.
grant_type	Set as password.
username	Specify the username of the user who wants to authenticate.
password	Specify the password of the user who wants to authenticate.

Example of the request body

Copy

Body request

client_id:dc-ui
grant_type:password
username:george.becker
password:my_password

Example of the cURL request

Copy

Get token

curl --location --request POST "http://{server}/auth/realms/{tenant}/protocol/openid-connect/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "client_id=dc-ui" \
--data-urlencode "grant_type=password" \
--data-urlencode "username=george.becker" \
--data-urlencode "password=my_password"

 

Response body

In the response body, you receive the bearer token in the access_token parameter. Also, you get the details about token expiration (in seconds).

Copy

{
    "access_token": "eyJhbGciOiJIUzI1LgK0A...",
    "expires_in": 1800,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI2LwYwEQQLk...",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "8a1c477d-e000-4f6e-98db-0589a64c8cdf",
    "scope": "email dc-scope profile"
}

Authenticate an API request with a bearer token

After you get the bearer token, you can specify it in the authorization header of an API request.

The following is an example of the API request with a bearer token added in Authorization, where “server” is the entry point for the Platform.

curl -X GET "https://{server}/dp/api/v1/aiconnections/types" 
-H "accept: application/json" 
-H "Authorization: Bearer {bearer-token}"

Error codes related to authentication & authorization

The DataClarity‘s API uses standard HTTP response codes to indicate whether an API request was successful.

If you receive one of the following responses, it means that your request was unauthenticated or unauthorized:

403 – Forbidden

The error means that the request cannot be authenticated. If you receive the 403 error response, ensure the following:

• Authorization header is sent

• Authorization header is formatted properly

• User’s token is valid and active

401 – Unauthorized

The user with the provided token does not have sufficient permissions for the requested action. Thus, if you receive the 401 error response, ensure that the user has a role with respective permissions assigned in Access Manager.

Client secret authentication

You can also authenticate some API calls with a client secret instead of a Bearer token. However, such authentication works only for the API calls related to back-end services that do not require separate authentication for each user. For example, you can execute a Python code using the DataClarity Data Science engine. However, Access Manager does not provide a default Client for such purposes, and therefore a new Client should be created and configured in the master console of Access Manager. Please contact the Customer Care Team for further configuration.