API Authentication with Service Credentials
This guide explains how to create and use Service Credentials to authenticate with our API.
1. Creating Service Credentials
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/