# How Authentication Works This reference article explains how the FleetFusion Geotab Add-In signs you in. It is aimed at administrators and technically curious users who want to understand the handshake, or who need to diagnose a sign-in problem. ## Overview The add-in does not have its own login screen. Instead, it uses the **Geotab session-exchange grant** to convert your existing MyGeotab session into a FleetFusion access token. The exchange happens automatically the first time you click an entry under the **FleetFusion** menu in a given session, and again whenever the token needs refreshing. ## The sign-in handshake The handshake has three steps. ### Step 1: Read the MyGeotab session When the add-in loads inside the MyGeotab iframe, it asks MyGeotab for the current session using the Geotab API call `api.getSession()`. MyGeotab returns four pieces of information: * The **database** name. * The **username** of the signed-in MyGeotab user. * A short-lived **session ID**. * The MyGeotab **server** the user is connected to. These values prove to FleetFusion that the user is genuinely signed in to MyGeotab. ### Step 2: Exchange the session for a FleetFusion token The add-in posts the four values to the FleetFusion auth server using the OAuth grant type: `urn:ietf:params:oauth:grant-type:geotab-session-exchange` The auth server validates the session against MyGeotab, looks up the matching FleetFusion user in the Organisation linked to that database, and issues credentials. ### Step 3: Receive the access token The auth server returns a FleetFusion **access token** (a JWT) and a **refresh token**. The add-in uses the access token on every subsequent request to FleetFusion APIs. ## Where the token is stored The access token is held in **browser memory only**. The add-in deliberately does not write it to localStorage or sessionStorage. This avoids problems with browsers that block third-party storage inside iframes, which is increasingly common. Because the token lives in memory, it is cleared automatically when you close or refresh the tab. The next time the add-in loads, the handshake runs again. ## Token refresh Access tokens are short-lived. The add-in tracks the token's expiry time and refreshes it **60 seconds before it expires**, in the background, so that long sessions do not interrupt your work. If a request to FleetFusion returns a **401 Unauthorized** response, usually because the token has expired sooner than expected, or the user's session was reset, the add-in: 1. Re-runs the Geotab session exchange (steps 1 and 2 above). 2. Retries the failed request with the new access token. You normally do not see this happen. ## Troubleshooting sign-in failures If you see an authentication error or a blank page when opening the add-in, the cause is almost always one of the following four: 1. **The MyGeotab user is not yet provisioned in FleetFusion.** Each MyGeotab user needs a matching FleetFusion user in the same Organisation. Ask your administrator to create the FleetFusion user, then retry. 2. **The browser is blocking third-party storage.** The add-in runs inside a MyGeotab iframe. If the browser blocks all third-party storage, the in-memory token strategy still works, but some browsers block the underlying network calls too. Allow third-party storage and cookies for the FleetFusion domain, or add it to the browser's allow list. 3. **The MyGeotab session has expired.** Refresh MyGeotab and sign in again, then re-open the add-in. The handshake re-runs with the fresh session. 4. **The FleetFusion auth server is unavailable.** If the FleetFusion service is temporarily unreachable, the exchange fails. Wait a few minutes and retry. If the problem persists, contact . > **Note:** The add-in never asks you for your FleetFusion password. If a page inside the add-in prompts for one, stop and report it to your administrator. ## Privacy and security The session ID handed to FleetFusion during the exchange is short-lived and only valid for the database it was issued for. FleetFusion does not store your MyGeotab password. Communications between the add-in and the FleetFusion auth server use HTTPS. ## Related articles * [Signing In](/geotab-add-in/getting-started/signing-in.md) * [Installing the Add-In](/geotab-add-in/getting-started/installing-the-addin.md) * [What Is the FleetFusion Geotab Add-In?](/geotab-add-in/getting-started/what-is-the-geotab-addin.md) * [Differences from the FleetFusion Web Portal](/geotab-add-in/reference/differences-from-web-portal.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.fleetfusion.ai/geotab-add-in/reference/how-authentication-works.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.