diff --git a/src/main/java/org/gcube/common/keycloak/KeycloakClient.java b/src/main/java/org/gcube/common/keycloak/KeycloakClient.java
index 28ccf74..27d9e12 100644
--- a/src/main/java/org/gcube/common/keycloak/KeycloakClient.java
+++ b/src/main/java/org/gcube/common/keycloak/KeycloakClient.java
@@ -634,24 +634,94 @@ public interface KeycloakClient {
*/
TokenResponse refreshToken(URL tokenURL, String clientId, String clientSecret, String refreshTokenJWTString)
throws KeycloakClientException;
-
- TokenResponse exchangeTokenForAccessToken(URL tokenURL, String oidcAccessToken, String clientId,
- String clientSecret, String audience) throws KeycloakClientException;
-
+
+ /**
+ * Exchanges a token for another access token for a specific client and a specific audience
+ *
+ * @param context the context where the Keycloak's is needed (e.g. /gcube
for DEV)
+ * @param oidcAccessToken the original access token to exchange
+ * @param clientId the authorized client's id
+ * @param clientSecret the authorized client's secret
+ * @param audience the requested token audience
+ * @return the exchanged token response
+ * @throws KeycloakClientException if an error occurs during the exchange
+ */
TokenResponse exchangeTokenForAccessToken(String context, String oidcAccessToken, String clientId,
String clientSecret, String audience) throws KeycloakClientException;
- TokenResponse exchangeTokenForRefreshToken(URL tokenURL, String oidcAccessToken, String clientId,
+ /**
+ * Exchanges a token for another access token for a specific client and a specific audience
+ *
+ * @param tokenURL the token endpoint URL
+ * @param oidcAccessToken the original access token to exchange
+ * @param clientId the authorized client's id
+ * @param clientSecret the authorized client's secret
+ * @param audience the requested token audience
+ * @return the exchanged token response
+ * @throws KeycloakClientException if an error occurs during the exchange
+ */
+ TokenResponse exchangeTokenForAccessToken(URL tokenURL, String oidcAccessToken, String clientId,
String clientSecret, String audience) throws KeycloakClientException;
+ /**
+ * Exchanges a token for another access and a refresh tokens for a specific client and a specific audience
+ *
+ * @param context the context where the Keycloak's is needed (e.g. /gcube
for DEV)
+ * @param oidcAccessToken the original access token to exchange
+ * @param clientId the authorized client's id
+ * @param clientSecret the authorized client's secret
+ * @param audience the requested token audience
+ * @return the exchanged token response
+ * @throws KeycloakClientException if an error occurs during the exchange
+ */
TokenResponse exchangeTokenForRefreshToken(String context, String oidcAccessToken, String clientId,
String clientSecret, String audience) throws KeycloakClientException;
-// TokenResponse exchangeTokenForOfflineToken(URL tokenURL, String oidcAccessToken, String clientId,
-// String clientSecret, String audience) throws IllegalArgumentException, KeycloakClientException;
+ /**
+ * Exchanges a token for another access and a refresh tokens for a specific client and a specific audience
+ *
+ * @param tokenURL the token endpoint URL
+ * @param oidcAccessToken the original access token to exchange
+ * @param clientId the authorized client's id
+ * @param clientSecret the authorized client's secret
+ * @param audience the requested token audience
+ * @return the exchanged token response
+ * @throws KeycloakClientException if an error occurs during the exchange
+ */
+ TokenResponse exchangeTokenForRefreshToken(URL tokenURL, String oidcAccessToken, String clientId,
+ String clientSecret, String audience) throws KeycloakClientException;
-// TokenResponse exchangeTokenForOfflineToken(String context, String oidcAccessToken, String clientId,
-// String clientSecret, String audience) throws IllegalArgumentException, KeycloakClientException;
+ /**
+ * Exchanges a token for another access and an offline refresh tokens for a specific client and a specific audience
+ * The refresh token will be of the offline type only if the original token has the offline_access
within its scopes
+ *
+ * @param tokenURL the token endpoint URL
+ * @param oidcAccessToken the original access token to exchange
+ * @param clientId the authorized client's id
+ * @param clientSecret the authorized client's secret
+ * @param audience the requested token audience
+ * @return the exchanged token response
+ * @throws IllegalArgumentException if the original token does'nt contains the offline_access
scope within its scopes or if is impossible to parse the access token as JSON
+ * @throws KeycloakClientException if an error occurs during the exchange
+ */
+ TokenResponse exchangeTokenForOfflineToken(String context, String oidcAccessToken, String clientId,
+ String clientSecret, String audience) throws IllegalArgumentException, KeycloakClientException;
+
+ /**
+ * Exchanges a token for another access and an offline refresh tokens for a specific client and a specific audience
+ * The refresh token will be of the offline type only if the original token has the scope offline_access
within its scopes
+ *
+ * @param tokenURL the token endpoint URL
+ * @param oidcAccessToken the original access token to exchange
+ * @param clientId the authorized client's id
+ * @param clientSecret the authorized client's secret
+ * @param audience the requested token audience
+ * @return the exchanged token response
+ * @throws IllegalArgumentException if the original token does'nt contains the offline_access
scope within its scopes or if is impossible to parse the access token as JSON
+ * @throws KeycloakClientException if an error occurs during the exchange
+ */
+ TokenResponse exchangeTokenForOfflineToken(URL tokenURL, String oidcAccessToken, String clientId,
+ String clientSecret, String audience) throws IllegalArgumentException, KeycloakClientException;
/**
* Introspects an access token against the Keycloak server.