Authorization

About Users & Concepts

tl;dr; Would you like to learn how to receive the Auth-Token?

Please refer to the section Make your first API call to learn more about that. Have fun!

About User-Tokens

In order to access any data within fulfillmenttools you need to possess valid credentials in the form of a username and a corresponding password. Our Auth Provider provides a JWT Token in exchange for such credentials, which needs to be sent along every issued request to any of the provided APIs.

The JWT Token itself is signed & contains your username, your role and your potential facility affiliation (see below). It has a Lifetime of 60 minutes and can be refreshed using the refresh token which comes with the response from the Auth Provider.

Currently there is no way on issuing machine-to-machine tokens. All provided access to the system is based on a user (which can be impersonated by a machine of course).

Roles and Permissions

In the fulfillmenttools platform there is a simple yet effective rights & permissions system in place. It grants access to data, that the user is allowed to see while it hides data from users, that are authenticated but not authorized to view data. The role also has impact on active features in API, backoffice or mobile clients.

Currently there is a fixed set of roles a user can take within the platform:

Role	Facility affiliation	Description
FULFILLER	yes	The Fulfiller is the role that takes care of the operative workflow, such as picking, packing and sending an order on the way. Therefore users of this role have primarily access to operatively needed parts of the system.
SUPERVISOR	yes	The Supervisor is allowed to configure the settings of certain facilities. Therefore a user of this role will primarily use the Backoffice Application as well as potentially other clients. The Supervisor role extends the role of the Fulfiller.
ADMINISTRATOR	no	The Administrator of a fulfillmenttools system is allowed to access all the functionality.

A user always has to have a known role in order to interact with the clients or via the API. This information is provided to the Identity-Provider and will be reflected in the JWTs, that is issued to the user.

Only information that comes within the signed JWT token is considered for authorization in the platform. That also means, that for example a role change can take up to 60 minutes for a user to become visible, because already issued JWT Tokens still remain valid. You can force acquiring a new role for example by asking the user to logout and login again.

Currently there is a 1:1 relationship between a user and a role: Any given user in the system can have exactly one role.

Facility affiliation

In order to prevents user of specific roles to read out data that they are not allowed to see (for GDPR reasons for instance) some roles are only assignable together with a mandatory reference to a facility.

Currently the list of available roles is fixed and cannot be extended by the client.

Use Case: Working with users via REST API

Creation of a new User

The following calls are allowed to the following roles: SUPERVISOR, ADMINISTRATOR

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "firstname": "Donna",
  "lastname": "Sheridan-Carmichael",
  "username": "dsheridan",
  "password": "fsdf6556",
  "roles": [
    {
      "name": "FULFILLER",
      "facilities": [
    "0AMSoRCbm7kSM3LJPoeH"
      ]
    }
  ]
}'

Response:
201 OK
{
    "customClaims": {
        "roles": [
            {
                "facilities": [
                    "0T1vKaEar0nuG58CxzA5"
                ],
                "name": "FULFILLER"
            }
        ]
    },
    "version": 1,
    "lastname": "Sheridan-Carmichael",
    "username": "dsheridan",
    "firstname": "Donna",
    "created": "2020-09-25T10:06:35.009Z",
    "lastModified": "2020-09-25T10:06:35.009Z",
    "id": "x5jrZrDHvYYs6HpaDICKYG4QuIk2"
ba

Operation is allowed by either a SUPERVISOR of facility 0AMSoRCbm7kSM3LJPoeH or an ADMINISTRATOR.

Use Case: Modifying the role of a user

curl -sSL -X PATCH 'https://your.api.fulfillmenttools.com/api/users/x5jrZrDHvYYs6HpaDICKYG4QuIk2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "version": 1,
  "actions": [
    {
        "action": 	"ModifyUser",
          "roles": [
              {
                "name": "SUPERVISOR",
                "facilities": [
              "0T1vKaEar0nuG58CxzA5"
                ]
              }
            ]
    }
  ]
}'

Response:
200 OK
{
    "lastname": "Sheridan-Carmichael",
    "customClaims": {
        "roles": [
            {
                "facilities": [
                    "0T1vKaEar0nuG58CxzA5"
                ],
                "name": "SUPERVISOR"
            }
        ]
    },
    "version": 2,
    "lastModified": "2020-09-25T10:13:27.236Z",
    "username": "dsheridan",
    "created": "2020-09-25T10:06:35.009Z",
    "firstname": "Donna",
    "id": "x5jrZrDHvYYs6HpaDICKYG4QuIk2"
}

Deleting a user

curl -sSL -X DELETE 'https://your.api.fulfillmenttools.com/api/users/x5jrZrDHvYYs6HpaDICKYG4QuIk2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>'

Response:
200 OK

When a user is deleted all currently active JWT Tokens of said user are invalidated. The user will not be able to use an issued token anymore.