API FUNDAMENTALS

GENERAL

The SLASCONE API follows the OpenAPI (3.0) specification, is HTTPS only, built using REST principles, following all state of the art best practices for API security.

All SLASCONE functions are invokable through the API, allowing a seamless integration with other back-office systems such as CRM/ERP etc.

You can easily test the API using our official API Test Center.

ZERO FOOTPRINT

No SLASCONE software components need to be distributed with your software, nor do you need any SLASCONE client libraries in your code. You just need to establish an https connection to the API.

However, for .NET integrations, we do provide a NuGet package.

AUTHENTICATION

In order to authenticate (regardless if you are testing the API using our Test Center or from your source code), you need to use an apiKey.

There are two apiKey types available (both can be found in the API Keys area of SLASCONE).

PROVISIONING KEY

• • The Provisioning apiKey (ProvisioningKey). This apiKey enables you to call all methods needed for licensing and analytics scenarios. In other words, this is the apiKey to be embedded in your software. This key authorizes the following API controllers:

    • data_gathering

    • lookup

    • provisioning

    • license (some endpoints)

SCOPE RESTRICTION

By default, a provisioning key can access all products. However, if you embed a provisioning key into multiple products, we recommend using a separate key for each product. This reduces the scope in the event of a compromised key.

V1 vs V2

Use V1 only if you have existing provisioning keys that access the data_exchange controller.

ADMINISTRATION KEY

The Administration apiKey (AdminKey) allows you to call ALL SLASCONE methods. This is meant for testing or administration or internal purposes only. It is not recommended embedding this key in your software.

In the API Keys area, you can:

• create multiple keys, e.g., for usage in different applications or scenarios
• activate/deactivate a key (in case of suspicious activity)

The swagger page includes the available authorizations per endpoint:

AUDIT LOG

When creating/editing any entity using one of the apiKeys, the LastModifiedBy field of the respective entity is going to be set to the ID of the respective key (i.e., ModifiedBy = '981f7853-d362-45b6-bede-23fdee3d0f08').

If you want to set a custom value instead, just add an http header LastModifiedBy = 'CustomValue'.

UPDATING ENTITIES

The majority of update operations are available through PATCH endpoints. When updating an entity it is recommended to:

1. retrieve the relevant object through the respective GET endpoint
2. update the necessary object fields
3. send the whole object (not only the updatet fields) in the PATCH endpoint

DIGITAL SIGNATURES

SLASCONE uses the HMACSHA256 algorithm in order to simultaneously verify both the data integrity and the authenticity, of every API response. This process is described here.

GENERATING CLIENTS

.NET

For .NET applications, it is highly recommend (but not mandatory) to use our official NuGet package, in conjunction with our GitHub examples.

OTHER LANGUAGES

You can easily generate clients in your programming language using the online swagger editor. Select file, import URL and type in:

https://api365.slascone.com/swagger/v2/swagger.json

Next select Generate client and choose the language of your choice. The end result is a zip file you can download with the generated client code.

Of course, there are many other tools generating clients based on an Open API specification.

COMMON PARAMETERS

Most API methods require all or some of the following parameters:

• isv_id: This can be found in the API Keys area of SLASCONE.
• product_id: This can be found in the Products area of SLASCONE. Select your product and click on the Copy Key icon.
• client_id: Each to be licensed client, needs to generate a unique device id.
• license_key: This is the license key generated from SLASCONE. It consists of n tokens. A license key can be used/activated n times.
• token_key: A license consists of n tokens. A token key can be used/activated only once (one client).

Your provisioning workflow (which means the API functions that need to be called) depends on your product's licensing mode.

WORKING WITH POSTMAN

We strongly recommend the usage of Postman, if available. You can easily start testing the API in Postman

using the following link (you can fork or copy the collection):

Make sure to edit your environment data (baseUrl, isvid etc.) as already explained in the first part of this article.

You are now able to run all relevant API requests such as activation:

ERROR HANDLING

The API methods might fail for a number of reasons. SLASCONE provides a comprehensive error handling framework.