5. Basic Auth vs API Key
From HOPEX V5 and onward, the method for authentication for API has evolved.
1. With a Basic Auth.
2. With an API Key (preferred choice)
Former Bearer Token is not available in V5. Oauth2 Authentication is not supported for the moment for API calls.
Depending on the use case you want to use the API you may use one or the other authentication method. Regardless of the chosen authentication methods the other headers and body information remain the same.
5.1. Basic Auth
The basic Auth allows you to access the API directly with credentials: login/password.
5.1.1. How to use it?
For example:
• 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.
• In a script in curl add the header Authorization: Basic and pass the encoded value of the login and password.
|
curl --location --request POST 'httpx://www.myserver.com/HOPEXGraphQL/api/ITPM' \
--header 'Content-Type: application/json' \
--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 with a login/password logic. It is nonetheless less secure than an API Key.
5.1.2. How to enable it?
You need to create a dedicated User/Password within the HAS console to be able to use it in API Call. This user can be:
• Admin user.
• HOPEX user that connects with a profile.
Process step:
1. Connect to HAS Console.
2. Select Modules > Authentication.
3. Select User accounts.
4. Click Create.
5. Fill in the form:
a) Enter a login (User Name) to your user.
b) Enter a Password or generate one.
c) Select the Role: Administrator or Custom.
d) Select if you allow to open a session on a specific Repository and Profile.
e) Enter the login of the HOPEX user.
f) Select the Environment (there should be only one).
g) Select the Repository (if more than one).
h) Select the Profile (if more than one)
i) Selection the Session mode: multi or single (see below for more details on what to chose).
j) Select the Connection mode: read/write or read only.
k) Click Submit.
You can now use this login/password for API call.
5.2. API Key
To access the API with an API Key you need to create it and define all the technical information:
• admin or user api key
• repository and profile to connect to.
Once done, the system gives you the API key. This API Key can be valid for all time or have a validity period.
5.2.1. Security
The API Key generated does not contain any information that can be decrypted or decoded.
5.2.2. Use case
It is recommended Authentication methods whenever possible. It is ideal when scripting, when developing external app, or when doing integration with external tools.
5.2.3. How to use it?
For example:
• In Postman when calling the API choose "API Key" and fill-in the API Key value.
o Key: x-api-key
o Value: xxxxxxxxx
Now you can make call to any endpoint.
• In a script in curl add the header x-api-key and pass the value of the API Key.
|
curl --location 'https://w-ogd/HOPEXGraphQL/api/ITPM' \
--header 'x-api-key: 5snybEHxGR8uTRAks2ySEgYs8t82rQ6KqkrcEsp9srw737WmPZcJvpk1gNctBCjVQZvBwrryaFzJkHk61Q1eFJex' \
--header 'Content-Type: application/json' \
--data '{"query":"query\n{\n application\n {\n id\n name\n }\n}","variables":{}}'
|
5.2.4. How to enable it?
You need to create a dedicated API Key in HOPEX Administration to be able to use it in API Call. This API Key can be:
• Admin API Key.
• HOPEX user that connects with a profile.
See Managing API Keys.
5.3. Multi or Single Mode
The mode choice changes the behavior in the back-end to process the request.
Choose:
• Multi for all purposes where you need responsiveness in the API calls.
• Advantage: you benefit from cache, ready to use process to respond your query.
• Drawback: not adapted to static website generation
• Single for heavy computing treatment. Ideal for heavy batch or static website generation.