User administration

TYRIOS makes it possible to manage users directly from API. Here are general rules for using the user API:

• TYRIOS depends on different module configurations. It depends on your configuration if an endpoint is available.
• It depends on your rights if you can call a specific endpoint.
• TYRIOS is an aspect oriented system. It depends on the concrete configuration, which fields are available and processes. In this document we will discuss the typical structure.

Authentication

The API endpoints of TYRIOS are only available for authorized users. Therefore, the user must be authenticated. There are two different authentication types:

• Authentication by BASIC authentication. The user account must have an activated REST API token. You need to send an appropriate BASIC authentication header.
• Authentication by mobile app registration. You need to send an appropriate app registration token.

Data structure

Users are a basic data structure in TYRIOS. Nearly every other data structure is at least in some way linked with a user using references. Due to the aspect-oriented nature of TYRIOS that means that it is very likely you have a individual data structure. Nevertheless, it is possible to describe a general data structures most instances have in common: UserData.

API endpoints

The general endpoint for the user administration is

https://[instance.de]/service/UserManagement

Creating a user

For creating a user, you need to create a user using a PUT request to the endpoint

https://[instance.de]/service/UserManagement/users

The body of your request needs to provide the UserData in json format. 

You can set with this method the password of the user, it will be automatically encoded and cannot be requested any more. If the user field "guestUser" is set to true, the system automatically creates a test user. In that case no nickName, birthday or password is required.

As response, you will get the complete UserData object.

It is not possible to create blank users with this method. 

Creating blank users

Blank users are an optimal solution in case you only know how the users should be threatened by the system, but you don't know any contact information so far. So it is a perfect possibility for marketing. To create blank users, you have to realize a PUT request to the endpoint

https://[instance.de]/service/UserManagement/users/blankUsers

The payload needs to provide the following data structure:

{
  amount: 10, //number of blank users which should be created, required
  preName: "blank", // first name of the blank user
  name: "user" // last name of the blank user
  tags: ["tag1","tag2"] // optional array with tags to identify the users, e.g. marketing campaign
} 

The method provides as response the following structure:

{
 users: [
   //list of UserData objects with the corresponding users
]
}

List all users

All available users can be retrieved using a GET request to URL:

https://[instance.de]/service/UserManagement/users/

The result is paginated with offset and length parameter. In addition, the endpoint supports filtering by filter parameter and sorting by sorting parameter. 

The filter parameter supports all fields and must be encoded as JSON data structure. 

The sorting parameter supports multisorting and must be encoded as JSON data structure.

The data response is providing a list of UserData objects with the following structure:

{
  count: 122, // number of elements matching the current request
  users: [
    // list of UserData objects, the number depends on the length parameter of your request
  ],
  pluginData: [
    //list of plugins (string) which can be loaded directly
  ]

}

Get a specific user

To get data from a specific user, you need to create a GET request to the URL

https://[instance.de]/service/UserManagement/users/[userID]

The response is the UserData object. 

Get one user by unique user hash

Each user has a unique user hash which identifies the user and which can be users for customer cards. You can call a user by user hash with a GET request to the URL

https://[instance.de]/service/UserManagement/users/byHash/[userHash]

Update a user

For updating a user, you need to send a POST request to the endpoint

https://[instance-domain]/service/UserManagement/users/[userID]

As payload, you have to send the complete user data including the id of the user. Due to the aspect oriented nature of the system, we recommend to first load the complete data structure and then to update it.

Deleting a user

NOT supported so far via REST API

Registering a user

You can also use the register functions to create a new user. In this context, there is more automated steps in the background:

https://[instance-domain]/service/UserManagement/users/registration

You can send the same data as JSON data as in the create step, however, an email might be sent to the user for further steps.

Generate User Barcode

You can get a user barcode to identify the user. The barcode uses the uniqueUserHash, which is not guessable

https://[instance-domain]/service/UserManagement/users/[userID]/barcode

Generate a direct login URL

TYRIOS supports direct login URLs. You can use these URLs to automatically log in a specific user while the user is redirected to a specific URL

To generate a directLoginUrl, you have to send a POST request to 

https://[instance-domain]/service/UserManagement/users/[userID]/directLogin

You have to post a JSON object with following parameters:

{
   "redirectURL": "https://instance.de/url", //absolute url the user should be redirected after login, required, max. length 255 characters
   "validUntil": null // unix timestamp until this link will be valid. If null, the link will never outdate.
}