How to Access the API

Asta7 can also be accessed using the REST API. The API docs can be found at https://hostname/gui-server/swagger-ui/index.html (Replace hostname with your own).

Authentication

Asta7 REST API uses OAuth2 for authentication. Standard OAuth2 endpoints can be used to obtain the tokens.

An Asta7 user is needed in order to access the REST API. Then the client: client and password: grant_type can be used to get the access_token required to access the API.

Send an x-www-form-urlencoded POST request to http://localhost/auth/realms/archive-manager/protocol/openid-connect/token to get the tokens.

Example Token Request using Credentials

curl -X POST http://localhost/auth/realms/archive-manager/protocol/openid-connect/token -H 'Content-Type: application/x-www-form-urlencoded' -d 'client_id=client&grant_type=password&username=sys_admin&password=am'

The response would look something like the following

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJvMmdlVzN2a21QSldEcmppbHFuc2xTU1I1cXJ5SlVXeHZHS0RDY19QXzFzIn0.eyJleHAiOjE2ODc3NTM0NTksImlhdCI6MTY4Nzc1MzE1OSwianRpIjoiMjUzMmE2NzMtODdlYS00ODA1LTg1ODktMTc2MzJlZTk3ZGE0IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdC9hdXRoL3JlYWxtcy9hcmNoaXZlLW1hbmFnZXIiLCJhdWQiOlsiY29yZSIsImFjY291bnQiXSwic3ViIjoiNTZlZGVmNGItNDkzMC00NTVjLWJkNzgtOWM4ZjBhZjUyZmMxIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiY2xpZW50Iiwic2Vzc2lvbl9zdGF0ZSI6IjVjNzg1ZWM2LTljM2YtNGVhNC1iMDJiLTQ4ZDlhNmIwNzk0OCIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsiaHR0cDovLzE5Mi4xNjguMi4xMTIiLCJodHRwOi8vbG9jYWxob3N0IiwiaHR0cDovL2xvY2FsaG9zdDozOTA0NSIsImh0dHA6Ly9sb2NhbGhvc3Q6MTAzMDAiLCJodHRwOi8vbG9jYWxob3N0OjQyMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbImFtfHN5c3RlbV9hZG1pbiIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJjb3JlIjp7InJvbGVzIjpbImFtX3VzZXIiXX0sImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsInNpZCI6IjVjNzg1ZWM2LTljM2YtNGVhNC1iMDJiLTQ4ZDlhNmIwNzk0OCIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwicHJlZmVycmVkX3VzZXJuYW1lIjoic3lzX2FkbWluIn0.Lnm2-bBLX7D0iz4nPlsvOGZ1tMct8j_1H-zgYfOKBbEEkTnTsf5Riuku_Zibr7yu-3oqp-BU0axz_NYe0uE2KpNZlm5GhBj4QddzJgiD27l8kNCbgEMXaLqKCPdTXdTHw3ZsJa8OssWspnmTVU3BR-Fv28uoyEuO-EzwRJWsKxpoGEBZibJ0_AsxrfLVG43TeeCDh1JASg7hWt2PnqHBN4DnZg3ka-sZmguulYUoDcXClirYY9YkP47IdV7HOllbG_0t144bLRaYQBMFIh92AE90s5ytAbISWuRDAxV8VaBrdc4G3HTtfZjCzzWToednfoPu7xPgPyXrn569nkuRbA",
    "expires_in": 300,
    "refresh_expires_in": 604800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIyMmFlZjBmMi1mYzhiLTQyZGYtYjNlNS0zZDljMjExYzVkMDEifQ.eyJleHAiOjE2ODgzNTc5NTksImlhdCI6MTY4Nzc1MzE1OSwianRpIjoiOTA0MTJkYTUtYzg2NS00OTExLWI0MTQtOThmMjI0ZWIzNjZjIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdC9hdXRoL3JlYWxtcy9hcmNoaXZlLW1hbmFnZXIiLCJhdWQiOiJodHRwOi8vbG9jYWxob3N0L2F1dGgvcmVhbG1zL2FyY2hpdmUtbWFuYWdlciIsInN1YiI6IjU2ZWRlZjRiLTQ5MzAtNDU1Yy1iZDc4LTljOGYwYWY1MmZjMSIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJjbGllbnQiLCJzZXNzaW9uX3N0YXRlIjoiNWM3ODVlYzYtOWMzZi00ZWE0LWIwMmItNDhkOWE2YjA3OTQ4Iiwic2NvcGUiOiJlbWFpbCBwcm9maWxlIiwic2lkIjoiNWM3ODVlYzYtOWMzZi00ZWE0LWIwMmItNDhkOWE2YjA3OTQ4In0.sHcTBQRSiexrZaCJUgp_RwQhAgYgteQlvuoCcV2RQMs",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "5c785ec6-9c3f-4ea4-b02b-48d9a6b07948",
    "scope": "email profile"
}

This is a standard OAuth2 token response. This method should be used only once to get the initial tokens, further requests should use the refresh token to get new access tokens.

It is recommended to do this process manually once and then use the refresh token in the script. This way we can avoid putting the user credentials in the script.

Example API Request using the Access Token

The access_token is required to access the APIs. Here is an example request to get the list of projects from Asta7

curl -X GET http://localhost/gui-server/api/asta7-project -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJvMmdlVzN2a21QSldEcmppbHFuc2xTU1I1cXJ5SlVXeHZHS0RDY19QXzFzIn0.eyJleHAiOjE2ODc3NTM0NTksImlhdCI6MTY4Nzc1MzE1OSwianRpIjoiMjUzMmE2NzMtODdlYS00ODA1LTg1ODktMTc2MzJlZTk3ZGE0IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdC9hdXRoL3JlYWxtcy9hcmNoaXZlLW1hbmFnZXIiLCJhdWQiOlsiY29yZSIsImFjY291bnQiXSwic3ViIjoiNTZlZGVmNGItNDkzMC00NTVjLWJkNzgtOWM4ZjBhZjUyZmMxIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiY2xpZW50Iiwic2Vzc2lvbl9zdGF0ZSI6IjVjNzg1ZWM2LTljM2YtNGVhNC1iMDJiLTQ4ZDlhNmIwNzk0OCIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsiaHR0cDovLzE5Mi4xNjguMi4xMTIiLCJodHRwOi8vbG9jYWxob3N0IiwiaHR0cDovL2xvY2FsaG9zdDozOTA0NSIsImh0dHA6Ly9sb2NhbGhvc3Q6MTAzMDAiLCJodHRwOi8vbG9jYWxob3N0OjQyMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbImFtfHN5c3RlbV9hZG1pbiIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJjb3JlIjp7InJvbGVzIjpbImFtX3VzZXIiXX0sImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsInNpZCI6IjVjNzg1ZWM2LTljM2YtNGVhNC1iMDJiLTQ4ZDlhNmIwNzk0OCIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwicHJlZmVycmVkX3VzZXJuYW1lIjoic3lzX2FkbWluIn0.Lnm2-bBLX7D0iz4nPlsvOGZ1tMct8j_1H-zgYfOKBbEEkTnTsf5Riuku_Zibr7yu-3oqp-BU0axz_NYe0uE2KpNZlm5GhBj4QddzJgiD27l8kNCbgEMXaLqKCPdTXdTHw3ZsJa8OssWspnmTVU3BR-Fv28uoyEuO-EzwRJWsKxpoGEBZibJ0_AsxrfLVG43TeeCDh1JASg7hWt2PnqHBN4DnZg3ka-sZmguulYUoDcXClirYY9YkP47IdV7HOllbG_0t144bLRaYQBMFIh92AE90s5ytAbISWuRDAxV8VaBrdc4G3HTtfZjCzzWToednfoPu7xPgPyXrn569nkuRbA'

The expires_in property in the response states the period of validation (in seconds) for the access_token. By default, this is 5 minutes. This can be modified from the Keycloak admin console. Log in to the Keycloak admin console, then go to Realm Settings > Tokens and change the Access Token Lifespan

Refresh Token

This token can be used to get new access tokens. Send an x-www-form-urlencoded POST request to http://localhost/auth/realms/archive-manager/protocol/openid-connect/token with grant_type: refresh_token to get the tokens. This token should be remembered to get the next access token.

Example Token Request using Refresh Token

This will provide the response in the same format as the previous one. As before the refresh token should be remembered for future usage.

Authorization

The authorization and screening will be applied based on the user that is being used for the authentication. So the user should have proper authorization and screening.