Making API requests to MyGeotab

Last updated August 2024

Service account overview

Service accounts are functionally similar to real user accounts in the MyGeotab database. A service account has a username, password, first name, last name, security clearance, etc. Service accounts are added to the database in the same way as a real user, from the MyGeotab application or with an API request.

Service accounts are used exclusively by your solution to make API requests against the MyGeotab database outside of user sessions. Service accounts must be used by integrated solutions, and not by people.

Using a service account

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

Common scenarios that require service accounts:

1. Your solution must periodically pull data from the MyGeotab database (GPS, Odometer, Fuel level, Device list, etc.)
2. Your solution must import changes to the database based on external triggers (Adding Zones or Routes, editing Email Templates, adding Rules, etc.)

Service account 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.

Service account details

Name

It is mandatory for the username of a service account to:

1. Be unique and specific to each customer’s MyGeotab databases. Each MyGeotab database needs a different service account name for your solution.
2. Include “-service”.
3. Specify the Partner organization/solution name, or both if they are different.
4. Include the customer database name if that makes the username unique.

✱ NOTE: Usernames do not need to be valid email addresses, but they can be.

Examples of proper service account usernames:

1. PartnerName-SolutionName-service@DatabaseName
2. SolutionName-service@PartnerName-DatabaseName
3. service-SolutionName@DatabaseName

If the database name is "myDatabase", the service account name can be:

1. "service-myDatabase@mySolution"
2. "mySolution-service@myDatabase"

Password

It is mandatory for service account’s passwords to follow the requirements below to ensure they are secured:

1. Minimum 12 characters
2. Contains an uppercase letter
3. Contains a lowercase letter
4. Contains a number
5. Contains a symbol, like $ or @

Security clearance

Security clearances determine what the account can do within the MyGeotab database.

If a service account is only pulling data from a database, the View only security clearance is recommended.

If the service account must make changes to the database, you must decide which Security clearance it needs by following this process:

1. From your own MyGeotab database, navigate to Administration > Users.
2. Click Clearances.
3. Select the Default user clearance from the available clearances. The built-in clearances are:
4. 1. Administrator
   2. Supervisor
   3. Default user
   4. Drive App user
   5. View only
   6. Nothing
4. From the Security features list, review the ones needed for your service account. For example, for an account that needs to access the MyGeotab map, enter the word “map” in the search box, and review the related security features.
5. If the required feature has a red-colored X beside it, it is not included in this clearance. If this happens, repeat steps 3 and 4 with the Supervisor clearance. If Supervisor also does not have the necessary clearance, assign your service account the Administrator clearance.

Custom security identifiers for Add-Ins

Custom security identifiers for MyGeotab Add-Ins are available and can be defined in the configuration.json file of Add-Ins. This adds them to the list of permissions available when editing clearances. These definitions can support multiple languages.

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

Adding a service account

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

1. Navigate to Administration > Users.
2. Click + User.
3. Enter the service account details to 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:

1. The Customer adds the service account manually.
2. The Partner adds the service account manually.
3. Service account is added automatically via the SDK.

The next sections detail each workflow.

Manually by the Customer

1. Send the Customer your solution’s Implementation Guide, which contains step-by-step instructions on how to add the service account to their MyGeotab platform.
2. Let the customer send you the service account credentials; for example, through a phone call.
3. Test the credentials to confirm that the solution can use the service account.

This method includes more manual work from both parties to set up the service account and address any issues with it in the future. However, it is convenient to set up.

Manually by the Partner

1. If your organization leverages Support staff with access to the Customer’s MyGeotab database to set up Customers, they can add the service account to the database by following steps in the Implementation Guide. The Customer must provide consent for the service account to be added.
2. Test the service account to confirm it works.

Automatically via SDK

1. When your Add-In is opened for the very first time by the very first user, check if the user has the ability to add new users to the database by checking their security clearance - it should be Administrator or Supervisor.
2. Have a message to inform the user that a service account will be added to their database, and record consent from the user.
3. Use the “Add” API call on the “User” object. The call should specify all the service account details (username, password, security clearance, etc.).
4. The Add-In should encrypt the service account credentials (AES-256 or TLS1.2) and securely send them to your backend for storage.

For Solutions that use an Add-In, this is the recommended approach to add the service account. It reduces the ongoing workload for your company and the Customer as well, and it makes the Add-In setup process easier.

Service Accounts login via SDK

To log into the application, the service account must perform the Authenticate API call, with a POST HTTP request where applicable. The Authenticate call receives the service account username, password, and the Customer’s database name as input.

If the Authenticate API call is successful, it returns a Login Result, which contains a Credentials object. The Credentials object will contain the username, database, and session ID of the service account’s 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 objects of future API calls will look like this:

{

“database”: <database name>

“username”: <service account username>

“sessionId”: <session id received from the result of Authenticate call>

}

Notice that the password is no longer being used when making API calls. Instead, you will use the session ID.

The session ID expires after 14 days, or if the MyGeotab server shuts down for any reason.

Using an expired or invalid session ID in an API call will result in the “Incorrect Login Credentials” error. When you see this, you should perform another Authenticate API call, to receive a new session ID.

✱ NOTE: A Service account should log into the application once every 14 days, because a sessionId lasts for up to 14 days. See the “Service Accounts login via SDK” for details on how to reuse the session ID.