The HIRO API requires API users to be authenticated. API users need to obtain an access token from the HIRO Auth API first, which is then used for subsequent API calls.
\nThe HIRO API distinguishes two types of API usage:
\nFrontend web applications that run in a web browser. These applications require the end user to login with his credentials.
\nTypically backend components or applications that run on a server. These applications use technical accounts and typically manage the credentials in the server application.
\nAt the moment, HIRO’s Auth API provides two types of authentication flows:
\nPassword flow
\nFor apps acting on their own (normally non-UI, such as Backend Services or Server Applications)
\nRequires for the password to be sent directly to HIRO in order to request for the access token.
\nUI flow
\nFor graphical interfaces, e.g.: browser apps
\nThe application will send the request for the token and HIRO will respond accordingly. However, the user\nneeds to login and authenticated first and then only the access token will be granted to the application.
\nIn order to use HIRO, you need to be authenticated and authorized. This means that you need to have a user\naccount that is tied to a username and password, which can be obtained from Almato AI.
\nThe same user account and password can also be used to authenticate via API, but a separate application key\nneeds to be supplied as well. The application key consists of client ID and client secret, that are also\nobtained from Almato AI. When authenticating via API, it will always be in the context of an application, which\nmeans that you are using the API as a user but through an application. This means that you will be identified\nas a user using a certain application to access HIRO.
\nAfter authentication, the user will receive the AUTH token and this token can then be used (while it is valid)\nto make API calls. Auth tokens typically expire after 1 hour, unless configured differently.
\nFor each new application (maybe a Connector, Acton Handler or service) that is accessing HIRO, a different application key\nmust be used, so that HIRO knows which application is accessing the system and data. Applications can be\nrevoked, without affecting other applications that need to access HIRO.
\nA backend application is an application which runs as a backend service. The backend application typically operates independent from the activities of individual frontend users.\nAuthentication for these types of applications use the OAUTH2 password flow to obtain access tokens.
In order to obtain a token, the following request must be executed (example using curl command):
\ncurl -X POST -H 'Content-type: application/json' --data-binary '{\"client_id\": \"$id\", \"client_secret\": \"$secret\", \"username\": \"$user\", \"password\": \"$password\"}' 'https://core.engine.datagroup.de/api/auth/6/app'with
\nclient_id being the id of the application
client_secret being the secret of the application
username being the username under which the application will operate
password being the password of the user
This will return the following result:
\n{\n \"_TOKEN\": \"$access token\",\n \"_APPLICATION\": \"$client_id\",\n \"_IDENTITY\": \"$ogit/name of the user\",\n \"_IDENTITY_ID\": \"$id of the user\",\n \"expires-at\": \"$expiration timestamp in ms\",\n \"type\": \"Bearer\"\n}Other option is to use OAUTH2 token flow which is same concept but use standard defined input and output
\ncurl -X POST -H 'Content-type: application/x-www-form-urlencoded' -H \"Authorization: Basic <<BASE64ENCODED($client_id:$client_secret)>>\" --data 'grant_type=password&username=$username&password=$password' 'https://core.engine.datagroup.de/api/auth/6/token'with
\nclient_id being the id of the application
client_secret being the secret of the application
username being the username under which the application will operate
password being the password of the user
This will return the following result:
\n{\n \"access_token\": \"$token\",\n \"expires_in\": \"$expiration time in seconds\",\n \"token_type\": \"Bearer\",\n \"refresh_token\": \"$refresh token\"\n}The application can use the token to access the HIRO Graph API.
\nA UI application is an application which only runs in the browser. Authentication must be done with the\nOAUTH2 implicit flow.
In order to start this flow, redirect the browser to:
\nGET https://core.engine.datagroup.de/api/auth/6/ui/?client_id={CLIENT_ID}&redirect_url=https://another.example.com/my/app/with client_id being the id of the application, and redirect_url the URL that will be redirected to upon\nsuccessful authentication. Please make sure that the redirect_url is correctly assigned to the application\nin HIRO IAM, so that the authentication flow works correctly. The Auth API will refuse to accept to unknown\nredirect URLs.
The user will be taken through the authentication process. If successful, the browser will finally be redirected to:
\nGET https://another.example.com/my/app/#accessoken={token}and the application can then parse the token from the # hash and remove it from the URL.
The HIRO Desktop framework uses the mechanism for UI applications described above. The HIRO Desktop SDK handles the token management for your application, so that you as developer do not need to take care of authentication flow.
\nFor a step by step example on how to authenticate via API, please refer to the tutorial First Steps with HIRO.
\n