This post concern version V3 or V4. For V5 go to this link Basic Auth vs API Key (HOPEX V5 and forward)
The HOPEX REST API based on GraphQL allows to be called in two way :
- With a Basic Auth
- With Bearer Token
Depending on the use case you want to use the API you may use one or the other.
Regardless of the chosen authentication methods the others headers and body information will remains the same.
Basic Auth
The basis Auth allow you to access the API directly with your credential : user/password.
Use case
The use case for this are integration with reporting tools like PowerBI, Tableau, QLik, BoldBI...
How to use it
- For instance, in Postman when calling the API choose "Basic Auth" and fill-in the user password. The information will be encoded with Base64 to avoid to be readable when sent.
- For instance, in a script in curl add the header Authorization: Basic and pass the encoded value of the login and password.
curl --location --request POST 'http://192.168.131.155/HOPEXGraphQL/api/ITPM' \
--header 'Content-Type: application/json' \
--header 'x-hopex-environment-id: rCE(taFnUXDC' \
--header 'x-hopex-repository-id: vqXt9MVvPjoL' \
--header 'x-hopex-profile-id: 757wuc(SGjpJ' \
--header 'Session-Type: API' \
--header 'Authorization: Basic V2Vic2VydmljZTpIb3BleA==' \
--data-raw '{"query":"query {\n application {\n id\n name\n cloudComputing\n }\n}","variables":{}}'
This authentication method is useful when you need to check identity and get the data in one call. In the back end the server will generate a bearer token that will then be used to get the data.
How to enable it
When you installed the REST API you must configure the web.config file to store the information about the client ID, Client Secret and Scopes.
In the IIS server where HOPEX GraphQL is installed ensure the web.config contains the informations :
- Example of file location : C:\inetpub\wwwroot\HOPEXGraphQL\web.config
<add key="AuthenticationUrl" value="http://192.168.131.155/UAS"/>
<!-- Mega UAS address-->
<add key="ClientId" value="HopexAPI"/>
<!-- Client Id (used for basic authentication)-->
<add key="ClientSecret" value="secret"/>
<!-- Client Secret (used for basic authentication)-->
<add key="Scopes" value="hopex openid read write"/>
<!-- Scopes (used for basic authentication)-->
Bearer Token
To access the API with a bearer token you will need to make 2 call :
- one to get the bearer token
- one to get the data
Once you have the bearer token you can reuse it and keep it for up to 60 minutes. You can refresh (to extend the validity) or revoke the bearer (to remove the validity) if needed.
Use case
It is the recommended Authentication methods whenever possible. It is ideal when scripting, when developing external app or when doing integration with external tools.
How to use it
- Make a first call to the UAS endpoint to get a bearer. How to get a bearer Token
- Make a call to the API with the retrieve bearer.
- For instance, in Postman when calling the API choose "Bearer Token" and fill-in the bearer value.
- For instance, in a script in curl add the header Authorization: Bearer and pass the value of the bearer.
curl --location --request POST 'http://192.168.131.155/HOPEXGraphQL/api/ITPM' \
--header 'Content-Type: application/json' \
--header 'x-hopex-environment-id: rCE(taFnUXDC' \
--header 'x-hopex-repository-id: vqXt9MVvPjoL' \
--header 'x-hopex-profile-id: 757wuc(SGjpJ' \
--header 'Session-Type: API' \
--header 'Authorization: Bearer 8eb2c5b3a05a8c744c0b4e35f295e095' \
--data-raw '{"query":"query {\n application {\n id\n name\n cloudComputing\n }\n}","variables":{}}'
How to enable it
It is the default behavior there is no specific configuration to do. the UAS module must be enabled and set as the authentication method of HOPEX.
