API Authentication and Authorization

12/08/2025

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.

It is possible to configure CORS headers—Allowed Headers, Allowed Methods, and Allowed Origins—directly via the properties files. These headers help secure cross-origin interactions by controlling which domains can access your resources and what actions they can perform and can be summarized as follows:

Access-Control-Allow-Headers: Specifies which custom headers can be included in cross-origin requests. You can allow specific headers or use '*' to allow all headers (except Authorization which must be explicit)
Access-Control-Allow-Methods: Defines which HTTP methods (GET, POST, etc.) are permitted when making cross-origin requests to the resource
Access-Control-Allow-Origin: Lists the domain names (origins) that are allowed to access the resources. Can be specific domains or '*' for all domains

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