API Authorization using OAuth 2.0

PoolParty’s API endpoints can be secured with either OAuth 2.0 or Basic Authentication. By default, both are enabled. This provides seamless compatibility with previous versions of PoolParty.

Note

We strongly recommend using OAuth 2.0 to authorize your access to PoolParty APIs to make sure that your API authentication method complies with high security standards on one hand, and on the other to benefit from performance enhancements offered by OAuth in comparison to Basic Authentication. OAuth is also the authorisation component of the PoolParty access and identity management. For information on how to disable Basic Authentication, refer to Disable Basic Authentication in PoolParty.

Requests to an API Endpoint

Basic Authentication is a way for transporting credentials within an HTTP request. Credentials for the authentication are always sent in every request and the actual authentication is carried out for each call by PoolParty in the background.

OAuth is a different and far more secure way for transporting credentials and in contrast to Basic Authentication it can securely transport far more that just credentials. OAuth is an authorization protocol which uses access tokens. An access token is a piece of data representing the authorization to access resources on behalf of the end-user. A request to an API endpoint using OAuth 2.0 requires two HTTP requests for the initial call, the first one requesting authentication and the second one going directly to the actual endpoint; all other calls then require only a single request without the need for further authentication.

Two HTTP Requests for the Initial Call using OAuth

Since a request to an API endpoint using OAuth 2.0 requires an authorization token in an HTTP header, you need to obtain this token first by sending the first of the two requests to Keycloak, the second request (with the token) is then sent directly to the API endpoint.

A request to Keycloak, authenticated with a username and password, to obtain an access token:
- URL: https://keycloak_server/auth/realms/servername/protocol/openid-connect/token
- Supported method: POST
- Required HTTP parameters: client_id, username, password, grant_type, client_secret
  Possible values for client_id: ppt (Thesaurus Server), extractor (Extractor) or ppgs (GraphSearch).
  grant_type must be password.
A sample request:
```
curl --location -g --request POST 'https://[KEYCLOAK_SERVER]/auth/realms/[SERVERNAME]/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]'
```
The actual request to the API endpoint authorized through the OAuth access token may look for instance like this:
https://servername/PoolParty/api/projects/6dec35a2-c401-41ab-b85d-ee56fa41f594/subtree/export
This is an example request. Before you send any POST request, make sure to include the access token you acquired from Keycloak as a bearer token.
Note
To interact with PoolParty via API, the user must be both authenticated and authorized, meaning that they must also have a role that permits API access and belong to a PoolParty group that provides access to a particular resource.User Roles - Server Permissions
Note
OAuth 2.0 requires a user account created and managed in Keycloak. This is the case even when single sign-on is in use for interactive users, that is when Keycloak is connected to an IDP. Keycloak does not yet support technical users managed by an IDP.

In this section: