Skip to main content

Authentication

To use Cartrack services and the Fleet API, you must have an account. The Cartrack Fleet API uses HTTP Basic Authentication. Requests must include an Authorization header containing a Base64‑encoded username:password pair. Always use HTTPS when sending credentials.

There are two primary user roles:

  • Administrator: Full access to account settings and fleet data; responsible for issuing credentials and managing user permissions.
  • Subuser: Access limited to features and data permitted by an Administrator. Fleetweb writes this as "sub-user"; the API reference and the endpoint and field names use "subuser" (/subusers, subuser_id).

Administrator​

Administrators sign in to Fleetweb with the credentials provided by Cartrack. Typical responsibilities include:

  • Issuing API credentials to subusers and integrations.
  • Creating and managing subuser accounts and access permissions in Fleetweb.
  • Maintaining fleet configuration and access controls.

Subuser​

Administrators can create and manage subusers in Fleetweb and assign permissions appropriate to their role. If you require access, request it from your organization's Fleetweb Administrator.

A subuser authenticates with the main account's username together with the subuser's own API password, so the username is shared across the account and only the password identifies the subuser.

Delivery access limits​

Subuser credentials are read-only across the whole Delivery family. Before you build an integration on them, check these limits:

  • Every POST, PUT and DELETE under /delivery/ returns 403 Forbidden when the request is authenticated with a subuser API password.
  • Most Delivery reads do accept subuser credentials, but they return the whole account's data with no filtering by subuser. A subuser API password does not narrow what a Delivery read returns.
  • A few Delivery reads require the main account's API password and also return 403 Forbidden for a subuser. GET /delivery/reports/drivers is one of them.

To create or update a delivery resource on behalf of a subuser, authenticate with the main account's API password and set subuser_id: as a request body field on delivery jobs and drivers, on create and update, and as a column in the uploaded file on POST /delivery/jobs/bulk-upload. That is the supported way to attribute a delivery write to a subuser.

These limits apply to Delivery only. On the rest of the API a subuser sees only what the Administrator has granted it, for example its permitted vehicle listings.

Fleetweb Access​

Use the region-specific Fleetweb URL for your account. Select your country below to open the correct Fleetweb endpoint:

Generating Administrator and Subuser API passwords​

In order to generate API credentials, you will need to connect to Fleetweb.

Sign in to your region's Fleetweb site (for example: https://fleetweb-<region>.cartrack.com).

Open the API Settings page at https://fleetweb-<region>.cartrack.com/settings/api-settings (Settings → API Settings in the Fleetweb menu). See screenshot below.

Access Admin Section

Administrator password​

Generate a new Administrator password following the on-screen prompts.

API Section Admin

Store the password securely and share it only with trusted personnel.

Subuser API password​

Use the "Generate User Credentials" button in the User Credentials section to create a new password for the integration or partner.

API Section User

Assign only the scopes/permissions required and store the password securely. Note that a subuser password cannot write to the Delivery endpoints: see Delivery access limits.

Notes

  • Use subuser accounts for external integrations when possible; reserve Administrator credentials for management tasks. An integration that writes to /delivery/ is the exception and needs the main account's credentials.
  • If your account is hosted in a different region, use the corresponding Fleetweb and API base URL — otherwise authentication will fail with HTTP 401.
  • Refer to the Base URLs page for region codes and endpoints.

Identifying Username and Password​

For Administrator, the username and password are found here:

Admin Username and Password

For subusers, the username will be the same as the administrator, but the password will be different. You can find the subuser password here:

User Username and Password

How to construct the header​

  1. Concatenate your username, a colon (:), and your password: username:password.
  2. Base64‑encode that string. This side can be useful: https://www.base64encode.org, however most API clients such as Postman offer the functionality to do this for you by selecting "Basic Auth" in the Authorization tab.
  3. Add the encoded value to the Authorization header prefixed with Basic.

Example (raw header)​

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

If you want, you can have it a try and decode this text here: https://www.base64decode.org

Quick examples​

curl

curl -u "username:password" "https://fleetapi-za.cartrack.com/rest/vehicles"

JavaScript (fetch)

const credentials = btoa(`${username}:${password}`);
fetch('https://fleetapi-za.cartrack.com/rest/vehicles', {
 headers: { 'Authorization': `Basic ${credentials}` }
});

Security best practices​

  • Always use HTTPS — never send credentials over plain HTTP.
  • Do not embed credentials directly in client-side code that may be public.
  • Store credentials securely (environment variables, secret managers, vaults).
  • Use least privilege: generate subuser API passwords for integrations instead of sharing administrator credentials. Delivery is the exception, because subuser credentials cannot write to /delivery/ and do not narrow what a Delivery read returns (see Delivery access limits).
  • Rotate and revoke credentials regularly; update integrations after rotation.
  • If you receive HTTP 401 Unauthorized, verify you're using the correct regional endpoint for your account (see Base URLs).