API Authentication and Authorization

Some of the API endpoints of the ADF Search Application are secured with OAuth 2.0. OAuth is an authorization protocol that uses access tokens. An access token is a piece of data representing the authorization to access resources on behalf of the end-user.

Before you can access an ADF Search Application API endpoint secured with OAuth 2.0, you must obtain an OAuth 2.0 access token from Keycloak (1). The access token may be re-used in subsequent API calls until it expires (2). By default, the token expires in 5 minutes.

Important

Although the ADF Search Application comes with several API endpoints accessible without an access token, we recommend that you include the OAuth 2.0 access token in every request.

To obtain an access token, a request authenticated with a PoolParty username and password must be sent to Keycloak, a third-party component PoolParty (and by extension the ADF Search Application) uses for user authentication and authorization:
- URL: https://keycloak_server/auth/realms/keycloak_realm/protocol/openid-connect/token
- Supported method: POST
- Required HTTP parameters:
  client_id – must be ppt
  username – username of an ADF Search Application user
  password – password of an ADF Search Application user
  Note
  To interact with the ADF Search Application via the API, the user must have a role in PoolParty that permits API access and belong to a PoolParty group with access to the ADF Search Application.
  grant_type – must be password
  client_secret – the secret of the client ppt
  Note
  Please ask your PoolParty administrator for the client secret of the client ppt.
A sample request – CURL:
```
curl -g --request POST 'https://keycloak_server/auth/realms/keycloak_realm/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=[USERNAME]' \
--data-urlencode 'password=[PASSSWORD]' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=ppt' \
--data-urlencode 'client_secret=[CLIENT_SECRET]'
```
A sample request – Postman:
The successful response will be a JSON object with an access_token field. Its value must be included as a bearer authorization token in the requests to the ADF Search Application API endpoints.
A sample request – CURL:
```
curl 'https://adf-dev.semantic-web.at/ADF/api/configurations/' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5...'
```
A sample request – Postman:

In this section:

API Authentication and Authorization

Important

Note

Note