Before you start:

Device Manager is our cloud-based Device Management Platform that provides visibility and control over your Digital Matter devices and ensures that they continue to perform at their best for longer.

Before you work with the API - we recommend familiarising yourself with Device Manager and the User Interface. For this, see Welcome to Device Manager.

The Device Manager API

Device Manager used to be named ‘OEM Server’ The API endpoints have not had their URL changed over in order to facilitate backwards compatibility. As such, OEM Server and Device Manager can be thought of as interchangeable terms. 

The WebAPI provides a wealth of features which enable control of device settings and more from a 3rd party platform.

This API is not required to simply ingest device data into a 3rd party platform. 
To access payload documentation, follow the link from the top right corner of the Device Manager UI. 

All functions (such as setting parameters) covered by the API can also be handled via the Device Manager User Interface, which most users choose to use. 

Why the API then? 

The WebAPI enables the following two sets of commands:

1. Device configuration and management actions such as: 
   1. setting parameters individually on devices, or parameter templates
   2. setting the device group
   3. setting connectors
   4. setting device comments

i.e. the API can be used to automate a provisioning workflow.  

2. Sending messages via Device Manager, down to the device (ASYNC messages) to control the device i.e. 
   1. Enable Recovery Mode
   2. Activate an immobiliser
   3. Toggle an output
   4. Reset the device

Some examples of it's use

1. Retrieve a list of devices and their details in order to import into a 3rd party front-end tracking platform, or other system
2. Provisioning devices, and setting the required parameters and connector automatically, and consistently. 
3. Allowing end users, support agents, or sales staff to set configurations from a 3rd party front-end platform, without needing to go back to Device Manager. 
4. Turning on recovery mode
5. Adjusting parameters in response to other events
   1. e.g. setting the device's timezone automatically - based on the location received in the device data

Authentication

Option 1: Create an API Key (recommended) 

API Credentials can be created via the Device Manager UI.

To access this menu, the API Credential Manager permission is required on your user account. See Users and Access

Permissions for the API Credentials work as per user account permissions. In that they can be restricted to only work on certain device groups, and perform certain actions. 

1. Set the Device Group which the credentials will be able to access/control. Generally this will be your client group - but it can be limited further down to individual client groups if required. And give the credentials a name. 
2. Generate a key, and optionally store it. 
3. Set the permissions. 

Option 2: Basic Auth with user account credentials

Basic authentication is supported, by passing the username:password combination for a given user account in the API call. 

You may wish to create a specific user account for use with the API - to do so, see Creating User Accounts.