• Services
  • Migration Topics
  • Integration
  • Concepts
  • Best Practices
  • Api
    • DomainObjectApi
    • Changelog
    • HIRO API Overview
    • HIRO Audit API
    • HIRO Graph - Gremlin Query
    • HIRO Graph Action API
    • HIRO Graph Auth API
    • HIRO Graph List API
    • HIRO Graph WebSocket API
    • Refresh Token

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.

The HIRO API distinguishes two types of API usage:

Web Applications (including HIRO Desktop applications)

Frontend web applications that run in a web browser. These applications require the end user to login with his credentials.

Backend Services and Server Applications (including e.g. connectors)

Typically backend components or applications that run on a server. These applications use technical accounts and typically manage the credentials in the server application.

At the moment, HIRO’s Auth API provides two types of authentication flows:

  1. Password flow

    • For apps acting on their own (normally non-UI, such as Backend Services or Server Applications)

    • Requires for the password to be sent directly to HIRO in order to request for the access token.

  2. UI flow

    • For graphical interfaces, e.g.: browser apps

    • The application will send the request for the token and HIRO will respond accordingly. However, the user needs to login and authenticated first and then only the access token will be granted to the application.

In order to use HIRO, you need to be authenticated and authorized. This means that you need to have a user account that is tied to a username and password, which can be obtained from Arago.

The same user account and password can also be used to authenticate via API, but a separate application key needs to be supplied as well. The application key consists of client ID and client secret, that are also obtained from Arago. When authenticating via API, it will always be in the context of an application, which means that you are using the API as a user but through an application. This means that you will be identified as a user using a certain application to access HIRO.

After authentication, the user will receive the AUTH token and this token can then be used (while it is valid) to make API calls. Auth tokens typically expire after 1 hour, unless configured differently.

For each new application (maybe a Connector, Acton Handler or service) that is accessing HIRO, a different application key must be used, so that HIRO knows which application is accessing the system and data. Applications can be revoked, without affecting other applications that need to access HIRO.

Obtaining a Backend Application Token (Password Flow)

A backend application is an application which runs as a backend service. The backend application typically operates independent from the activities of individual frontend users. Authentication 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):

curl -X POST -H 'Content-type: application/json' --data-binary '{"client_id": "$id", "client_secret": "$secret", "username": "$user", "password": "$password"}' 'https://core.arago.co/api/auth/6/app'


  • client_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:

  "_TOKEN": "$access token",
  "_APPLICATION": "$client_id",
  "_IDENTITY": "$ogit/name of the user",
  "_IDENTITY_ID": "$id of the user",
  "expires-at": "$expiration timestamp in ms",
  "type": "Bearer"

Other option is to use OAUTH2 token flow which is same concept but use standard defined input and output

curl -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.arago.co/api/auth/6/token'


  • client_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:

  "access_token": "$token",
  "expires_in": "$expiration time in seconds",
  "token_type": "Bearer",
  "refresh_token": "$refresh token"

The application can use the token to access the HIRO Graph API.

Obtaining a UI Application Token (UI Flow)

A UI application is an application which only runs in the browser. Authentication must be done with the OAUTH2 implicit flow.

In order to start this flow, redirect the browser to:

GET https://core.arago.co/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 successful authentication. Please make sure that the redirect_url is correctly assigned to the application in HIRO IAM, so that the authentication flow works correctly. The Auth API will refuse to accept to unknown redirect URLs.

The user will be taken through the authentication process. If successful, the browser will finally be redirected to:

GET 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.

Access Tokens in HIRO Desktop Applications

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.


For a step by step example on how to authenticate via API, please refer to the tutorial First Steps with HIRO.