Managing User Access via the Telematics Guru API

The Telematics Guru Client API v3.0 lets you enable or disable an existing user account and replace the assets that a user can access within an organisation. Use these endpoints to keep Telematics Guru access in step with your identity provider or another access-management system.
 

Before You Begin

Identify the API host for your Telematics Guru instance. See The Telematics Guru API for guidance on finding your instance and its Swagger documentation.
 

Authenticate as a user with the UserManage permission. Send your bearer token in the Authorization header.
 

Obtain the target organisation ID and the user's email address. You can find organisation IDs using the Organisations GraphQL query or GET /v2/user/organisations on your API host.
 

To replace another user's asset access, your own account must have full asset access in that organisation.
 

In the examples below, replace {apiHost} with your instance's API hostname, such as api-apac03.telematics.guru, and {organisationId} with the target organisation ID. Replace the example email address and IDs with the intended user's details and valid IDs from that organisation.
 

Find Asset, Project and Department IDs

Use the GraphQL API for Telematics Guru to look up the records before replacing a user's access. Open your instance's GraphQL query builder at https://{apiHost}/graphql/, authenticate, then use the Operation Builder to select assets, projects or departments for the target organisationId. Under nodes, select each record's name and its ID field. The builder shows the available field names and generates the query for you.

If the results span multiple pages, retrieve the remaining pages using first and after with a stable sort order, as described in the GraphQL guide. Match names to IDs within the target organisation; do not copy IDs from another organisation or use the illustrative IDs below.
 

REST Lookup Alternative

You can also retrieve these records using the following endpoints on the same API host:

GET https://{apiHost}/v3/assets/{organisationId}
GET https://{apiHost}/v3/organisation/{organisationId}/projects
GET https://{apiHost}/v3/organisation/{organisationId}/departments

Use id from each asset record, projectId from each project record, or departmentId from each department record. Build the complete intended access selection before sending the replacement request.
 

Authentication

Obtain a bearer token using POST /v3/user/authenticate on your API host. The request uses application/x-www-form-urlencoded; its fields include Username, Password and Otp. Use the returned accessToken in subsequent requests. For authentication background, see Getting Authenticated.

Authorization: Bearer {your_token}
Content-Type: application/json

Enable or Disable a User

This endpoint changes whether an existing user account is enabled, without deleting the account or its history. Disabling is the recommended way to remove access for someone who has left.
 

Request URL

PATCH https://{apiHost}/v3/organisation/{organisationId}/user/enabled

Request Body

To disable the example user:

{
  "email": "jane.doe@example.com",
  "isEnabled": false
}

To enable the same user, send the same request with "isEnabled": true.
 

Organisation and Account Rules

The user's home organisation must match organisationId. A user mapped into this organisation from another home organisation cannot be enabled or disabled here and is reported in the same way as an unknown email address.
 

A user who has not accepted their invitation cannot be enabled or disabled through this endpoint. Enabling would bypass the invitation process where they set their password; disabling would not prevent them from accepting the invitation.
 

Enabling a suspended user does not remove the suspension. Suspension continues to block sign-in and API keys.
 

Response and Effect

A successful request returns 200 OK. Disabling takes effect immediately: the existing web session is rejected on its next request, password and single sign-on logins are disabled, and further API requests using the user's existing tokens or API keys are refused. The user's history is preserved.
 

Replace a User's Asset Access

This endpoint replaces the assets that a user can access within one organisation. The user must already have access to that organisation, but it does not need to be their home organisation. Users shared from another organisation can be managed here.
 

Request URL

PUT https://{apiHost}/v3/organisation/{organisationId}/user/access

Request Body

Send email to identify the user and the required accessType to select one mode. Include only the ID fields for that mode.

IDs supplied for another mode are rejected rather than ignored. Every supplied ID is validated before changes are written. If validation fails, the user's current access remains unchanged.
 

Example Request Bodies

All assets:

{
  "email": "jane.doe@example.com",
  "accessType": 0
}

Specific assets. These illustrative IDs must be replaced with valid asset IDs:

{
  "email": "jane.doe@example.com",
  "accessType": 1,
  "assetIds": [101, 102]
}

Specific projects:

{
  "email": "jane.doe@example.com",
  "accessType": 2,
  "projectIds": [1, 2]
}

A single department. Replace the illustrative department ID:

{
  "email": "jane.doe@example.com",
  "accessType": 3,
  "departmentId": 10
}

Response and Effect

A successful request returns 200 OK. The submitted mode and selection replace the user's existing access selection for this organisation; matching project and department alert subscriptions are cleared.
 

Troubleshooting

Next Steps

Review the complete intended access selection before adding these requests to an automated workflow. Use your instance's Swagger documentation to confirm the request definitions. For other integration tasks, see The Telematics Guru API and Retrieving Telemetry Data via the Telematics Guru API.