API Authentication

CTC requires user authentication for APIs, so the first call required is the login interface to validate user credentials. The login API is an HTTP POST that requires three parameters:

  • Transmit the username and password in the body of the post.
  • Place the application key in the header along with the Content-Type.

You can see the URL, header, and body text in the example below:

📘

Note

The username and password are often the same credentials used for the admin interface; however, it is possible that some users will have API access without permissions to view the admin interface.

URL = "https://connect.calamp.com/connect/services/login?useAuthToken=true"
header = {'Content-Type'       : 'application/x-www-form-urlencoded',
          'calamp-services-app': '<application key for your client>'
         }
body = {'username': <username>,
        'password': <password>
       }

The HTTP status for a successful login will be 200. The response will include a cookie with an authorization token.

Taking Advantage of the Persistent authToken

After a login is completed, the authToken is valid until one of the following occurs:

  • It expires.
  • It is invalidated by calling the logout API.

🚧

Important Note

Customers successfully using the CTC API after the initial login should continue to use the same authToken until it becomes invalid.

Please refrain from calling the CTC login API before every API call.

WARNING: Be aware that if your users repeatedly call the login API instead of using the authentication token, you will be considered in violation of our fair-usage policies. Noncompliance may result in request throttling, higher-response latencies, or other such restrictions.

If the authentication token becomes unexpectedly invalid, CTC will return an HTTP 401 error. The 401 error is the official indication a new login is required.

Using the authToken After Login

After you are logged in, ALL subsequent API calls require the appKey and authToken in the header.
Here is an example header for subsequent calls:

{             'Accept':'application/json;charset=UTF-8',
 'calamp-services-app':'<application key for your client',
              'Cookie':'authToken=SkNCMEU1SGRhY1BmQUdNaTl0b1V4USUzRCUzRDpnakdPemM2Mkw4WnJxQjRzRWs0VmRnJTNEJTNE’
}

The authToken will authorize future calls, but subsequent calls to specific endpoints may have required request parameters and data. See the API documentation for each endpoint’s detailed specification.

Additional Authentication and Authorization Detail

A full application note on authentication and authorization is available here.