Service account overview

A service account is required when your solution needs to access or modify a MyGeotab database without an active user session.

If your solution needs to access data in a customer's MyGeotab database, or make changes to the database when there is no active user interacting with the solution, it requires a service account.

Common scenarios that require service accounts include:

• Your solution must periodically pull data from the MyGeotab database (GPS, odometer, fuel level, device list, and so on).
• Your solution must import changes to the database based on external triggers (adding zones or routes, editing email templates, adding rules, and so on).

There is no cost to create a service account, but some customer services may result in data costs.

There is no cost associated with creating an additional user in a MyGeotab database. However, some customer services may result in data costs to the service account end-user. Contact your Partner for details.

Review the required fields and settings when configuring a service account in MyGeotab.

{
  "method": "Set",
  "params": {
    "typeName": "User",
    "entity": {
      "id": "USER_ID",
      "password": "NEW_PASSWORD"
    },
    "credentials": {
      "database": "DATABASE",
      "userName": "USER_NAME",
      "sessionId": "VALID_SESSION_ID"
    }
  }
}

Add-Ins can define custom security identifiers in their configuration file to control access at a granular level.

Custom security identifiers for Add-Ins can be defined in the configuration.json file of an Add-In. This adds the identifiers to the list of permissions available when editing clearances, and supports multiple languages.

The Administrator clearance remains non-editable and has all custom clearances enabled by default. All other default or system clearance levels only allow editing of custom security identifiers, while keeping system-defined default identifiers non-editable.

Learn the three workflows for adding a service account to a MyGeotab database.

To add a service account to a database via the MyGeotab UI:

1. Navigate to People > Users & Drivers.
2. Click Add.
3. Enter the service account details in all required fields.
4. Click Save.

You must decide who is responsible for adding the service account to the database. The three common workflows are described below.

The customer manually adds the service account to their database using your solution's implementation guide.

1. Send the customer your solution's implementation guide, which contains step-by-step instructions for adding the service account to their platform.
2. Have the customer send you the service account credentials through a secure channel.
3. Test the credentials via the API to confirm that the solution can use the service account.

This method requires more manual effort from both parties to set up the service account and to address any issues in the future, but it is straightforward to configure.

A Partner with access to the customer's database can add the service account on the customer's behalf.

1. If your organization uses support staff with access to the customer's database, they can add the service account by following the steps in the implementation guide. The customer must provide consent for the service account to be added.
2. Test the credentials via the API to confirm that the solution can use the service account.

For Add-In solutions, the recommended approach is to add the service account automatically using the SDK when the Add-In is first opened.

1. When your Add-In is opened for the first time by the first user, check whether that user has the ability to add new users to the database by verifying their security clearance — it must be or Supervisor.
2. Use the Add API call on the User object. The call must specify all service account details (username, password, security clearance, and so on).
3. Encrypt the service account credentials (AES-256 or TLS 1.2) and securely send them to your backend for storage.

For solutions that use an Add-In, this is the recommended approach. It reduces the ongoing workload for both your company and the customer, and simplifies the Add-In setup process.

Learn how service accounts authenticate using the Authenticate API call and manage session IDs.

To log in, the service account must perform the Authenticate API call using a POST HTTP request. The Authenticate call takes the service account username, password, and the customer's database name as input.

If the call is successful, it returns a LoginResult, which contains a Credentials object. The Credentials object includes the username, database, and session ID of the newly created session. The session ID can be used in place of the password in all future API calls.

Almost every API call besides Authenticate requires a Credentials object as input. If your service account has a session ID, the Credentials object for future API calls will look like this:

{
  "database": "<database name>",
  "username": "<service account username>",
  "sessionId": "<session ID received from the Authenticate call>"
}

The password is not used once a session ID has been obtained.

The session ID expires after 14 days, or if the MyGeotab server restarts for any reason. Using an expired or invalid session ID results in an Incorrect Login Credentials error. When this occurs, perform another Authenticate API call to receive a new session ID.