API FUNDAMENTALS

API OVERVIEW

The SLASCONE API follows the OpenAPI 3.0 specification, is available over HTTPS only, and is designed according to REST principles. All SLASCONE functions are accessible through the API, which enables integration with back-office systems such as CRM or ERP platforms. You can also test the API using the official API Test Center.

CLIENT INTEGRATION MODEL

No SLASCONE software components need to be distributed with your software, and no SLASCONE client libraries are strictly required. In principle, an HTTPS connection to the API is sufficient. For .NET integrations, SLASCONE also provides an official NuGet package.

AUTHENTICATION

To authenticate against the API, whether from your source code or when testing through the API Test Center, you need an API key. SLASCONE provides two API key types, both available in the API Keys area.

Authentication is performed by sending the API key as an HTTP request header with each API call. This applies both to application integrations and to manual testing in tools such as Postman or the API Test Center. Depending on the use case, either a ProvisioningKey or an AdminKey must be used.

Provisioning Key

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

• data_gathering

• lookup

• provisioning

• license (some endpoints)

Example

The following request sends a license heartbeat using the ProvisioningKey as an HTTP request header.

POST /api/v2/isv/{isv_id}/provisioning/heartbeats HTTP/1.1
Host: api365.slascone.com
Content-Type: application/json
ProvisioningKey: ••••••

{
  "client_id": "c714a7b9-f41f-4f6f-91e4-7390074611c5",
  "operating_system": "10.0",
  "product_id": "3eac5004-d894-43e2-f057-08de85317187",
  "software_version": "23"
}

Scope Restriction

By default, a provisioning key can access all products. However, if you use provisioning keys across multiple products, it is recommended to create a separate key for each product. This reduces the scope of exposure in the event that a key is compromised.

V1 vs V2

Use V1 only if you have existing provisioning keys that still access the data_exchange controller. For new integrations, V2 should be the default choice. The API documentation indicates which endpoints and authorizations are available.

Administration Key

The AdminKey can access all SLASCONE methods. It is intended for testing, administration, and internal use, and should not be embedded in distributed software. In the API Keys area, you can create multiple keys for different applications or scenarios and activate or deactivate keys if suspicious activity occurs.

Example

The following request creates a product feature using the AdminKey as an HTTP request header.

POST /api/v2/isv/{isv_id}/products/3eac5004-d894-43e2-f057-08de85317187/features HTTP/1.1
Host: api365.slascone.com
Content-Type: application/json
AdminKey: ••••••

{
  "id": "9aa85f64-5717-4562-b3fc-2c963f66afa6",
  "product_id": "3eac5004-d894-43e2-f057-08de85317187",
  "name": "Name"
}

API Key Administration

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:

COMMON PARAMETERS

Most API methods require some or all of the following parameters: isv_id, product_id, client_id, license_key, and token_key. The exact set depends on the endpoint and on your product’s licensing mode.

• isv_id
  This can be found in the API Keys area.

• product_id
  This can be found in the Products area. Select the relevant product and copy its key.

• client_id
  Every licensed client must generate a unique device id. SLASCONE provides separate guidance on generating a unique client ID.

• license_key
  This is the license key generated by SLASCONE. It consists of n tokens, and a license key can be used or activated n times.

• token_key
  A license consists of n tokens. A token key can be used or activated only once for one client.

Your provisioning workflow, meaning the API functions you need to call, depends on the licensing mode configured for your product.

Signature Public Key

This can be found in the Signature area.

UPDATING ENTITIES

Most update operations are available through PATCH endpoints. When updating an entity, the recommended pattern is:

1. Retrieve the current object through the corresponding GET endpoint.
2. Update the necessary fields.
3. Send the complete object to the PATCH endpoint, not only the changed fields.

This pattern helps ensure that the update request reflects the full intended entity state.

DIGITAL SIGNATURES

SLASCONE uses the HMACSHA256 algorithm to verify both the integrity and the authenticity of every API response. Separate documentation describes the exact validation process in more detail.

TESTING THE API

API Test Center

The API Test Center, based on Swagger UI, can be used to inspect endpoints, review request and response schemas, and execute API calls directly in the browser. For authenticated endpoints, authorize first with the appropriate API key header, then enter the required parameters and request body for the selected operation. This is useful for validating payloads, testing individual endpoints, and reviewing live responses before implementing the calls in your application.

Postman

The article provides a Postman collection and an environment file that you can copy or fork. Before running requests, make sure to adjust your environment values such as baseUrl and isv_id, as described earlier in the article. Once configured, you can execute the relevant API requests directly, including activation flows.

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

AUDIT LOG & SPECIAL HEADERS

Audit Log

When you create or edit an entity using one of the API keys, the LastModifiedBy field of that entity is set to the ID of the respective key by default. If you want to provide a custom value, add the LastModifiedBy HTTP header with your desired value.

LastModifiedBy Header

In order to explicitly override the default value you can explicitly send the LastModifiedBy header with that user identifier. This is especially useful in complex integration workflows.

x-webhook-control Header

API requests can include the x-webhook-control header. If the called endpoint would normally trigger a webhook, setting this header to suppress prevents that webhook from being invoked.

GENERATING CLIENTS

.NET

For .NET applications, it is highly recommended, 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 enter:

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 for generating clients based on an OpenAPI specification.

ERROR HANDLING

API methods can fail for different reasons. SLASCONE provides separate documentation with a more comprehensive error handling framework. That guidance should be used together with the fundamentals in this article when implementing a production-ready integration.

API VERSIONING

Always use V2 of the API. V1 is obsolete.

API COMPATIBILITY LEVEL

In order to address complex scenarios while ensuring backwards compatibility, there are minor differences within V2, depending on the environments' compatibility level.