Getting Started

Organisational users are sub-users of a given client account. Any user with the appropriate privileges can create a sub-user within the same client account, and then the sub-user can login to the Tillhub dashboard using the organisation's (client account) name. A staff member can also become a sub-user.

The organisational login is utilising the same machnism depicted in the basic authentication tutorial, but it requires as well the organisation name as a part of the login request.

Creating an organisational user

Below is a simple example of creating a new sub-user. A sub-user inherits his/her parent user settings and may alter them according to his/her assigned permissions, set as scopes. The parent user settings configuration ID can be retrieved via the configurations API.

curl 'https://api.tillhub.com/api/v0/configurations/<YourClientAccountID>/<ParentConfigurationID>/users' \
  -H 'authorization: <YourBearerToken>' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{
      "user":
        {
            "id":null,
            "email":"max.mus@tillhub.de"
        },
        "description":null,
        "active":true,
        "user_id":null,
        "scopes":null,
        "username":"max.mus@tillhub.de",
        "secret":"myPassword",
        "locations":null,
        "firstname":"Max",
        "lastname":"Mustermann"
    }' \
  --compressed

A typical response would be:

{
  "status": 200,
  "msg": "Sub-user added.",
  "request": {
    "host": "api.tillhub.com",
    "id": "aebb4ce3-0f89-4b66-968f-29f453532e52d"
  },
  "count": 1,
  "results": [
    {
      "id": "043b66c4-de9f-4f65-985a-fad84c184bc2",
      "created_at": {
        "iso": "2020-01-07T17:56:45.461Z",
        "unix": 1610042205461
      },
      "updated_at": {
        "iso": "2020-01-07T17:56:45.592Z",
        "unix": 1610042205592
      },
      "metadata": null,
      "groups": null,
      "scopes": null,
      "attributes": null,
      "user": {
        "id": null,
        "email": "max.mus@tillhub.de"
      },
      "description": null,
      "active": true,
      "role": null,
      "parents": null,
      "children": null,
      "blocked": false,
      "configuration_id": "<ParentConfigurationID>",
      "user_id": null,
      "deleted": false,
      "api_key": null,
      "key": null,
      "username": "max.mus@tillhub.de",
      "name": null,
      "locations": null,
      "firstname": "Max",
      "lastname": "Mustermann"
    }
  ]
}

Authenticating an organisational user

The following example demonstrates how to authenticate as an organisation user. The name of the organisation can be retrieved from the client account administrator. The response will carry a new Bearer token to be utilised with API calls.

curl 'https://api.tillhub.com/api/v1/users/auth/organisation/login' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{
      "organisation":"<YourOrganisationName>", 
      "username":"max.mus@tillhub.de",
      "password":"myPassword"
      }' \
  --compressed

A typical response would be:

{
  "status": 200,
  "msg": "Authentication was good.",
  "errors": [],
  "request": {
    "host": "api.tillhub.com",
    "id": "6f2dd32e-bc36-3453-8a8f-10e937baf8e3"
  },
  "user": {
    "id": "<ParentUserID>",
    "name": "<ParentUserName>",
    "legacy_id": "<YourClientAccount>"
  },
  "token": "<NewBearerToken>",
  "token_type": "Bearer",
  "sub_user": {
    "id": "043b66c4-de9f-4f65-985a-fad84c184bc2",
    "role": null,
    "scopes": null,
    "username": "max.mus@tillhub.de",
    "locations": null,
    "active": true
  },
  "features": {
    "vouchers": true,
    "inventory": true,
    "fiscalisation": false
  },
  "expires_at": "2020-01-22T19:03:51.000Z"
}