API Authentication with Service Credentials
This guide explains how to create and use Service Credentials to authenticate with our API.
1. Creating Service Credentials
Note: Creating Service Credentials requires admin access. Contact your administrator if you do not have the required permissions.
- Log in to CARS and navigate to
Service → 
Service credentials in the left-hand menu. - Click the
(New service credentials) button in the top toolbar. - In the dialog that appears, fill in the following:
- Name (required) – Give the credentials a recognizable name.
- Has all installations – Toggle this on if the credentials should have access to all installations, or leave it off and manually select the desired installations from the Selectable installations list.
- Permissions – For each permission category (Alarms, Installations, Visualisation, Maintenance, Analysis, Forwardings, User management, Modules), check the access levels you want to grant: Read, Write, and/or Moderate.
- Click Save to create the credentials. You will receive a client_id and client_secret — store these securely, as the secret will not be shown again.
2. Requesting an Access Token
Send a POST request to the token endpoint with the following x-www-form-urlencoded parameters:
|
Parameter |
Value |
|
grant_type |
client_credentials |
|
client_id |
Your client ID |
|
client_secret |
Your client secret |
|
scopes |
Semicolon-separated list of scopes (see below) |
Scopes
Scopes define which permissions the token should have. Each scope consists of a category name and an access level, separated by a comma. Multiple scopes are separated by a semicolon ( ; ).
|
Access Level |
Permissions Granted |
|
1 |
Read |
|
2 |
Read & Write |
|
3 |
Read, Write & Moderate |
|
Available Scope Categories |
||
|
Alarm |
VariableType |
Setpoints |
|
Installation |
InstallationDriverProperty |
ScheduleSettings |
|
Location |
InstallationTypeDriverProperty |
ResetAlarms |
|
User |
RestApiCoupling |
Maintenance |
|
Role |
Tag |
MultiSourceProfile |
|
Cause |
Note |
UserAvailability |
|
InstallationType |
InspectionReport |
Transparency |
|
Forwarding |
MapManagement |
VisualisationDashboard |
|
ForwardingGroup |
Rtc |
ServiceCredentials |
|
ForwardingSchedule |
EventLog |
Track |
|
Profile |
ConnectionLog |
|
Example
|
Installation,1;Location,1 |
→ Read access to Installations and Locations |
|
Installation,2;Alarm,3 |
→ Read+Write on Installations, full access on Alarms |
Example Request
|
POST /token HTTP/1.1 Content-Type: application/x-www-form-urlencoded grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scopes=Installation,1;Location,1 |
Response
|
{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...", "token_type": "Bearer", "expires_in": 3600 } |
3. Using the Access Token
Include the access token in the Authorization header of every API request:
|
GET /api/v1/some-endpoint HTTP/1.1 Authorization: Bearer YOUR_ACCESS_TOKEN |
4. Notes
- Token expiry: Tokens expire after the period indicated by expires_in (in seconds). Request a new token when it expires.
- Scope: The scope requested when acquiring a token cannot exceed the permissions configured on the credentials.
- Security: Never expose your client_secret in client-side code or public repositories. Treat it like a password.
- Documentation: More information about the API can be found at https://cars-api.carsonline.eu/