Authentication

User Authentication Flow¶

sequenceDiagram
    autonumber
    actor User
    participant POSM
    participant CoreAPI
    participant Database
    POSM->>User: Login Screen
    User->>CoreAPI: email/password
    CoreAPI->>Database: verify credentials
    Database-->>POSM: PIN Token
    POSM->>User: PIN Screen
    User->>CoreAPI: PIN
    CoreAPI->>Database: verify PIN
    Database-->>POSM: Access Token
    CoreAPI-->>User: Logged in
    opt Internal App
        User->>CoreAPI: Create App
        CoreAPI->>Database: Save Client ID / Client Secret
        Database-->>POSM: Client ID / Client Secret
        User->>CoreAPI: Generate App Token
        Database-->>POSM: Access Token & Refresh Token
    end

Internal Application¶

You can create Applications for your account. Each application can have multiple tokens with individual access permissions. With the Token Manager in the Connect Dashboard https://connect.inventorum.com/apps you will be able to create Apps to give 3rd Parties defined access to your account.

Treat these carefully as they allow the user to read / write / delete data of your account based on the given permission.

Create an App¶

Login to https://connect.inventorum.com/apps with your account email, password and PIN.
Now you can see your apps after clicking on “My Apps / Meine Anwendungen”
You should create an App for every Project (like Locamo.de) or if you give access to an agency. Give it a proper name and press “+”.
Now your app is created and you already see the CLIENT ID and CLIENT SECRET. Generate a token to finish. (Good to know: You can delete the app any time. The number of apps is not limited.)
You will be asked to setup the scopes. Check the definition above to see which kind of access will be needed.
Now you see the Access Token (that is valid for 24 hrs) and the Refresh Token. Use that or hand it over to your technical contact.

Usage¶

Standard query¶

curl -X GET \
'https://app.inventorum.com/api/products/?page=1' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer [ACCESS TOKEN]'

Refresh a token¶

For getting a new Access Token you'll need to use the Refresh token.

Request¶

curl -X POST \
https://app.inventorum.com/api/auth/token/ \
-u '[CLIENT ID]:[CLIENT SECRET]' \
-d 'grant_type=refresh_token&refresh_token=[REFRESH TOKEN]'

Response¶

Now you received the new Access Token. Attention: Also the Refresh Token will be renewed here. You have to save it to issue a new token the next time.

{
"access_token": "[ACCESS TOKEN]", "token_type": "Bearer",
"expires_in": 36000,
"refresh_token": "[REFRESH TOKEN]", "scope": "orders:read orders:create orders:update
basic:read basic:create basic:update customers:create products:read products:update"
}

Old procedure for API Applications issued before 2019¶

Authentication¶

In order to use the INVENTORUM API, a client (any application that would like to use our API) needs to authenticate first. While our API supports the full OAuth 2.0 authentication flow, we issue client_id and secret currently on request via api_support@inventorum.com.

Access Token¶

The client_id and secret generated by the customer service is needed to generate the final token to be used for using the enpoints. To get this access token, use the following request:

curl -X POST \
  https://app.inventorum.com/api/auth/token/ \
  -u '{{client_id}}:{{secret}}' \
  -d 'grant_type=password&username={{email}}&password={{password}}'

where {{client_id}}:{{secret}} is from Customer Service.

Sample response:

Status 200 OK
{
    "access_token": "THIS_IS_YOUR_FINAL_TOKEN",
    "token_type": "Bearer",
    "expires_in": 36000,
    "refresh_token": "XpSSppFcfsZpjaFylUlTjApcv23QUs",
    "scope": "customers shop.products.publishing products images inventories tax_types orders categories"
}

Given a valid access token, it must be sent with every request in the HTTP header Authorization. Besides that, every request should also contain the Accept header, set to accept JSON responses as this is the primary data exchange format:

Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Sample response for invalid token:

Status: 401 (Unauthorized)
Body:
{
    "error": {
        "fields": {},
        "description": "Invalid token",
        "key": "token.invalid"
    }
}

Authorization¶

An OAuth access token is always connected to a user, so all API requests are performed in the user_scope. Generally, INVENTORUM distinguishes between accounts and users. One account hereby stands for one retail store, which can have many users, each of which can have different roles (e.g. owner, manager, staff). Through these roles, users can have various permissions, which affects the availability of specific endpoints for specific users and therewith access tokens.

For the time being, the API documentation does not contain any information about required permissions and access tokens are only issued for owner users, which have all permissions by default. This, however, will change on the API is fully published.

Scopes¶

Apart from application level permissions (e.g. user can update inventory), access tokens additionally come with one or more scopes according to the OAuth 2.0 specification. Similar to the access token issuing, the scope is currently manually defined per access token and can be adapted by a request via api_support@inventorum.com.

In case a given access token does not have the required scope for a particular endpoint, the API will respond as follows:

$ curl -s -H 'Authorization: Bearer TOKEN' https://app.inventorum.net/api/...
Body:
{
    "error":{
        "fields": {},
        "description": "Your scope does not allow access here.",
        "key": "scope.wrong"
    }
}

In such a case, please request the accessed scope (endpoint) for the used access token via api_support@inventorum.com.