Any API request requires an access token from HIRO™ and once the token is obtained, the HIRO™ backend\nwill always check whether the token is valid or not, whether the API request is to be granted or\ndenied. The access token contains the details of the user and application that is accessing the API.
\nIn HIRO, the Auth API is used to obtain access tokens. When\na developer creates an application, the application needs to authenticate with the Auth API so that\nproper access can be granted to that application.
\nAs explained in more detail in the Authentication article, HIRO provides 2 types of authentication flows:\npassword flow and UI flow.
\nIn HIRO, data and access is governed by means of roles (or permission groups). Each account created will\nbe assigned to one or multiple roles. In HIRO, the creation of roles provides two purposes:
\nto grant permissions to access data
\nto provide role-based control of available features and flows in the user interfaces.
\nBy default, for any HIRO customer there is always one role defined that represents the whole customer\norganization (e.g. customer-domain.com). Data owned by this organization-wide role is available to all\nmembers of the organization. Customers may partition their data into multiple roles, e.g. per division\nor team, if data access should be further restricted. For example, team-based roles might be called\n it.customer-domain.com, hr.customer-domain.com, and finance.customer-domain.com.
\nUsers are also assigned IAM roles according to their user role in the HIRO user interface, i.e.:
\nKnowledge Expert: knowledge-expert
Subject Matter Expert (SME): implicitly specified by absence of knowledge-expert role
Administrator: org-admin
As such, new user accounts are automatically assigned to the organization role (all members), and\nhave the SME role for the user interface, unless configured differently by the administrator.
\nData access is determined on a per-vertex level in HIRO. In general, for most entity types the allowed\ndata access operations (whether creating, reading, updating or deleting) are determined by the vertex\nattibutes below:
\nogit/_owner=<account_or_role> \t: For the data to be shared (read and write)
\nogit/_reader=<account_or_role>\t: For data to be shared (read only)
\nIf the ogit/_owner attribute of a vertex contains a specific account name, only this user has read/write\naccess to this vertex. Be careful when you want to restrict data access to a single user account.\nTypically, the ogit/_owner attribute is set to a data access role of the whole organisation or a team\n(see above). In this case, any account that is assigned the role specified in the owner attribute will\nhave read/write access to that vertex. This user can modify the vertex and even delete the vertex.
In the same way, any account associated with the role specified in the ogit/_reader attribute will\nhave read permission for that vertex.
Attention: By default, if a vertex is created without specifying the ogit/_owner attribute, the owner\nwill be set to the account id of the creator, and the vertex will be accessible only to this user. Ensure\nthat you set the owner attribute correctly if you want other users (and the HIRO Engine!) to see the data.
Each application using the HIRO API needs to be registered and gets assigned an application key, consisting\nof client_ID and client_secret. This means that the username and password are used to identify and\nauthenticate the user, while the application key (consisting of client_ID and client_secret) is used to\nidentify the application.\nDuring the authentication flow, the application passes along the application key together with the user\ncredentials, and access tokens are always issued for the specific combination of user and application.
\nBy design, access tokens will expire after a few hours. If the access token is expired, HIRO will return\nthe proper response (e.g. HTTP status code 401) to the application and the application must retrigger the\npassword flow in to receive the access token.
\nThe HIRO libraries for Java and Javascript handle most token related operations internally when the\nproper settings are initialized.
\nAn example for non-UI applications are Connectors. Connectors transfer data from a customer’s existing\nsystem to HIRO. Connectors are normally run as a backend service without dedicated user interface.
\nThe app identifiers (client_id and client_secret) will be provided and used for all API\ninteractions of the connector. As a best practice, a separate service user account should be registered\nfor each connector, so that the origin of data can be traced.
\nThe HIRO Desktop framework provides an infrastructure to host different browser\napplications on the platform. So the web applications are hosted on the HIRO ™\nSaaS Cloud and are delivered to the user’s web browser. The HIRO Desktop framework\nalso takes care of listing and launching the available apps, handling the user\nlogin flows, and managing user sessions.\nBy running the UI applications inside the HIRO Desktop framework, access tokens\nare fully-handled by the framework, which means that developers do not have to\nmanage the access tokens.
\nHowever, as a UI app developer, you need to take care of data access permissions by\nsetting the data owner (and reader) correctly when a vertex is created by the\napplication. An example would be when a HIRO Desktop application has an input\nform for a user to enter data into HIRO. The application needs to ensure to set\nthe ogit/_owner attribute on the new vertices correctly to the data access role\n(permission group) that should have read/write permissions.
When designing a new applications, the developer needs to consider and plan the\nintended data access permissions, and then implement it consistently.
\nHead over to HIRO Auth API for examples on how to get a token.
\nIn most cases, when developing Connectors, the Graph REST API will be used.\nHowever, there are also other types of APIs that can be utilised, i.e. the Websocket API\nand Event Stream. For Websocket API and Event Stream, a special handling of\naccess tokens and token refresh is required. Websocket connections may stay active\nlonger than the token lifetime. Therefore, the Websocket API supports a mechanism\nto refresh expired tokens.
\nFor more information on the access token for Websocket API and Event Stream,\nplease refer to the HIRO Websocket API Reference.
\nWhen data is injected to HIRO™ by Connectors, this data should typically be\nprocessed by the HIRO™ Engine for automation of tasks. Hence, to ensure that\nthe HIRO™ Engine can access and work with the data injected by the Connector,\nit is important to set the ogit/owner attribute correctly when creating the\nvertices. As long as there are no special data access requirements, it is a good\npractice to set the the ogit/_owner field to the data access role of the\ncompany (e.g. _customer-domain.com). This will ensure that the HIRO™ Engine can\nprocess the data, and that your end users can view the data in the HIRO™ frontend.