To interact with the Ctrack API, you'll need to obtain the following if you do not already have:
Crystal Credentials
Subscription Key (Ocp-Apim-Subscription-Key)
Sign Up:
Register on the Ctrack Developer Portal if you haven't done so already.
Generating a subscription:
Log in to your account.
Go to the "API Keys" section.
Click "Generate New Key" and follow the prompts.
Secure Your API Key:
Treat your API key like a password. Do not share it publicly.
If you suspect your key has been compromised, regenerate it immediately.
The Ctrack API is protected by JWT authentication as well as a subscription key. Each request made to the API requires you to have the following headers present in your requests:
x-token
The "x-token" header consists of a JWT, obtainable by running the Login method and supplying your Ctrack Crystal credentials.
ocp-apim-subscription-key
The "ocp-apim-subscription-key" header is an additional layer of authentication and identification. This header value is essential in all requests made to the service.
Once you have your Subscription Key and your Crystal credentials ready, you can start calling the API service. We'll start off by calling the Login endpoint to obtain our JWT token (token to be used in the X-Token header). Below is an example using cURL:
curl --location 'https://stgapi.ctrackcrystal.co.za/api/Authenticate/Login' \
--header 'content-type: application/json' \
--header 'Ocp-Apim-Subscription-Key:<subscription-key-goes-here>' \
--data '{
"username": "<crystal-username-goes-here>",
"password": "<crystal-password-goes-here>"
}'
If your parameters are valid, the service will return a 200 with the following response structure:
{
"validToUtc": "2024-08-07T14:04:32Z",
"jwt": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9........"
}
The "jwt" field contains your x-token header used to authenticate all subsequent requests.
the "validToUtc" contains the lifetime of the token. If a call is made using the token after the given date-time has passed, the token will be deemed as invalid and the service will return a 401 status code. Token are valid for 15 minutes
To ensure fair usage and prevent abuse, Ctrack enforces rate limiting on API requests. Here are the key details:
Rate Limit: 40 requests/minute.
Exceeded Limits: If you exceed the rate limit, you will receive a 429 Too Many Requests response. Retry your request after a short delay.
The Ctrack API uses standard HTTP status codes to indicate the success or failure of a request. Here are some common codes:
200 OK: The request was successful.
400 Bad Request: The request was invalid or cannot be otherwise served.
401 Unauthorized: Authentication failed or the API key is missing.
403 Forbidden: You do not have permission to access the requested resource.
404 Not Found: The requested resource does not exist.
429 Too Many Requests: Rate limit exceeded.
500 Internal Server Error: An error occurred on the server.