The CalAmp K-12 JSON API (JavaScript object notation application programming interface), at https://jsonapi.synovia.com, enables you to pull data from our servers about your fleet, add entities such as devices and vehicles to your account, and make any necessary updates.

You can go to https://jsonapi.synovia.com/swagger/index.html to find a list of all the available methods.

To use our JSON API, you'll need to have authorized users with the proper credentials.

You can find details on login authentication, response structure, and error codes in the sections below.

Authentication

The API uses OAuth 2 and JSON web tokens (JWT) for authentication. The initial call to the API will be to validate the user. If this is successful, the server will return back a JWT that will be valid for 12 hours. This token will need to be included in the authorization header for every subsequent call.

Note: The value of the authorization header for all subsequent calls should be "Bearer XXX ," where XXX is the JWT.

Authorization Sliding Expiration

Each authorized request returns the set-authorization header. This header holds the new JWT with the updated expiration time. To keep a user signed in, this value should be set in the authorization header.

API Key Validation

Each request must have an x-api-key header. The value is the API key that is used for the CalAmp K-12 SOAP (simple object access protocol) API authentication. These are the required headers:

Logging in to the API

As mentioned earlier, the initial call to the API will be to validate the user. If this is successful, the server will return back a JWT that will be valid for 12 hours. A JWT consists of three parts: a header, a payload, and a signature. The payload returned from the server will contain the following data:

• un: The username of the person who logged in.
   
• an: The account number.
   
• cid: The customer ID that corresponds to the account number.
   
• zid: The internal ID of the user.
   
• exp: The expiration time of the token.
   
• nbf (not before): The time the token becomes valid. This field does not need to be examined as the token will always be immediately valid.
   
• iat (issued at): The time the token was issued.

Request

• URL: /auth/signin
   
• Verb: POST
   
• Parameters (as JSON):
  • userName: The case-insensitive email address of the user that is trying to log in
     
  • accountNumber: The customer account number
     
  • password: The user's password, which is case sensitive
     

Here is an example of a request:

1  {

2      "userName":"user@email.com",

3      "password": "myP@ssw0rD",

4      "accountNumber": "12345"

5  }

Response

• Token: The JWT generated by the server after a successful login. Store this value and include it in every subsequent call in the authorization header.

Here is an example of a response:

1  {

2      "success": true,

3      "result": {

4         "token": "eyJhbGciOiJ6IkpXVCJ9.eyJ6aWQiOiIzIiwidW4iOi" 

5      },

6      "error": null

7  }

Note: Your actual token will be much longer than what is in line 4.

Response Object

Each response has a common basic structure:

• success: The request was successfully executed, with a value of true or false.
   
• result: The requested result object, which will be the asked-for data if the request was successful; if it failed, the value will be null or an empty object.
   
• error: The requested error details object, which will be the error code and its friendly message if the request failed; if it was successful, the value will be null.
  • message: The error message
     
  • code: The error code

Here is an example of a successful response:

 1  {

 2      "success": true,

 3      "result": {

 4         "data1": "some data",

 5         "data2": { 

 6             "something": 1

 7         }

 8      },

 9      "error": null

10  }

Here is an example of a failed response:

 1  {

 2      "success": false,

 3      "result": {

 4         "data1": null

 5      },

 6      "error": {

 7         "message": "Missing 'x-api-key' header",

 8         "code": "B-2"

 9      }

10  }

Error Codes

The following tables explain what the authentication, base, and validation errors mean.

Authentication Errors

Base Errors

Validation Errors