Copilot.cx Server API

Copilot.cx is an integrated software solution for Consumer IoT companies solving data, connectivity and user communication needs.

You are here

The Server API allows Copilot.cx to collect meaningful events from your Users and your Things. Events that happen in your system should be reported to Copilot.cx reflecting important actions typically performed the application or the physical product (thing). Use Copilot.cx Report API in order to inform Copilot.cx regarding User and Thing creation/update, status changes and interactions.

Please note: Use of Copilot.cx Management API allows access to private user data and should be allowed only from your own trusted servers, not to be accessed by end-users' clients.

Functionality overview

  • Collect API - The Copilot.cx Collect API enables you to send events from your server to Copilot.cx so that you can engage with your customers in order to increase satisfaction and drive incremental revenue.
  • Consent API - Control on whether end-user's data is allowed to be processed by Copilot.

Authentication

In order to integrate with Copilot.cx Server API, you would need to authenticate your API calls using Basic Authentication supplying the CLIENT_ID and CLIENT_SECRET. Those credentials will be provided by the Copilot.cx Customer Success representative.

💡 CLIENT_ID and CLIENT SECRET credentials should be saved and secured properly in order to prevent data theft.

How to build the header

The Authentication header is built from an 'authentication scheme' part and a 'credentials' part, separated by a space. The authentication scheme should be Basic, and the credentials part should be built by concatenating the CLIENT_ID value, a single colon character (":"), and the CLIENT_SECRET value, encoded to base64.

💡 You can create the Authentication token on bash shell by using the following command:
echo Basic $(echo -n <CLIENT_ID>:<CLIENT_SECRET> | base64) Alternatively, use the Basic Authentication option in your http client.

Authentication errors

In case of Authentication header does not exist or token is invalid a HTTP error code 401 and following HTTP body will be returned:

{
    "reason": "AUTH.UNAUTHORIZED"
}

Example

In case of the following credentials:

  • CLIENT_ID : ABABABABQQIRZ
  • CLIENT_SECRET : k9H2Nd3T5j5EW2Fu160l11Hal3x3oa

The credentials part will be:

QUJBQkFCQUJRUUlSWjprOUgyTmQzVDVqNUVXMkZ1MTYwbDExSGFsM3gzb2E=

The Authorization header, which should be added to each of your API calls, should look like that:

Authorization: Basic QUJBQkFCQUJRUUlSWjprOUgyTmQzVDVqNUVXMkZ1MTYwbDExSGFsM3gzb2E=

Schema

The Server API is accessible over HTTPS. All data is sent and received as JSON.

Timestamps are returned in ISO 8601 format and include seconds and milliseconds. For example: yyyy-MM-dd'T'HH:mm:ss.SSS'Z. The timezone is always set to UTC. For example: 2019-01-29T16:31:57.121Z

Required headers

Every request should contain this Content-Type header:

Authorization: Basic <YOUR_CREDENTIALS_PART>
Content-Type: application/json
Collect API →