Starting from HOPEX V5 the method for authentication for API has evolved.
- With a Basic Auth.
- 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 others headers and body information will remain the same.
Basic Auth
The basis Auth allow you to access the API directly with credentials : loing/password.
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 '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.
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 :
- Connect to HAS Console
- Click the menu Modules >> Authentication
- Click "User accounts"
- Click "Create"
- Fill in the form
- Give a login to you user
- Give a password or generate one
- Select the Role : Administrator or Custom
- Select if you allow to open a session on a specific repository and profile
- Give the login of the HOPEX user
- Select the environment (there should be only one)
- Select the repository (if more than one)
- Select the profile (if more than one)
- Selection the session mode : multi or single (see below for more detail on what to chose)
- Select the connection mode : read/write or read only.
- Click submit
You can now use this login/password for API call.
API Key
To access the API with an API Key you need to create it and defined all the technical information.
- admin or user api key
- repository and profile to connect to.
Once you will have defined this information the system will give you the API key. this API Key can be valid for all time or have a validity period.
Security
The API Key generate does not contains any information that can be decrypted or decoded.
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.
How to use it
- For instance, in Postman when calling the API choose "API Key" and fill-in the API Key value.
- Key: x-api-key
- Value : xxxxxxxxx
Now you can make call to any endpoint.
- For instance, 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":{}}'
How to enable it
You need to create a dedicated API Key within the HAS console to be able to use it in API Call. This API Key can be :
- Admin API Key.
- HOPEX user that connects with a profile.
Process step :
- Connect to HAS Console
- Click the menu Modules >> Authentication
- Click API Keys
- Click "Create"
- Fill in the information
- Name : for you to remember what this API key will be used for
- Expiration date : if you want to limit the validity period of this API Key
- Description : for you to remember what this API key will be used for
- Select the Role : Administrator or Custom
- Select if you allow to open a session on a specific repository and profile
- Give the login of the HOPEX user
- Select the environment (there should be only one)
- Select the repository (if more than one)
- Select the profile (if more than one)
- Selection the session mode : multi or single
- Select the connection mode : read/write or read only.
- Click submit
- Copy/paste the API Key and save it for later use
You can now use this login/password for API call.
Caution :
- the API key will appear on the screen only once so keep it !
- there is no mean to regenerate the API key. You will have to reset all the parameters to create a new one.
- the API cannot be displayed later to get it again
Mode Multi or Single
This mode will change the behaviour in the back-end to process the request. When to choose which one :
Multi : for all purposes where you need responsiveness in the API calls.
- Benefit : you benefit from caches, ready to use process to respond your query
- Inconvenient : not adapted to static website generation
Single : for heavy computing treatment. Ideal for heavy batch or static website generation
- Benefit : you benefit from dedicated process. Adapted to heavy computation that will need several minutes/hours to responds.
- Inconvenient : take time to response so.
Before I click on save, I see person, profile and repository. But once I save when i open it, those 3 values are not there any more. I tried creating a new user but I still see the same scenario
