Authentication

  • Updated on Feb 26, 2026
  • Published on Feb 24, 2026
  • 2 minute(s) read
Prev Next

Overview

Authentication is the most important service in your integration, as it is the gateway to your system. Beyond just verifying a username and password, the authentication response is also responsible for delivering all critical configuration data that builds the user's in-app experience. This includes what items users see on their dashboard, what tools are available in their navigation menu, their unique API token to maintain their session, and much more.

The purpose for Authentication is twofold:

  1. Authenticate Users: It is the "front door" that validates a user's credentials (like username and password) against your system to grant them access.

  2. Configure the App: After a successful login or session validation, your system's response delivers all the critical data that dynamically builds that specific driver's in-app experience.

How It Works

The Authentication API has three methods, each with a distinct purpose.

Initial Login: POST /authenticate

  • Purpose: The mobile app uses this when the user first enters their username and password

  • Your System's Job: Verify the credentials

    • If valid, your system generates a unique api_token to send back alongside other user and configuration data

Verify Session: GET /authenticate/{token}

  • Purpose: The mobile app uses this frequently in the background (e.g., when a driver re-opens the app or moves between pages) to quickly verify that their API token is still valid and to display the latest and greatest data for the user.

  • Your System's Job: Verify that the api_token is active.

    • If active, return a successful response with the user’s current configuration. The user’s mobile app will reflect any updates included in your response.

Custom Settings Update: PUT /authenticate/{token}

  • Purpose: This is used when a user changes a custom setting inside the app and the app needs to save that change to your web service.

  • Your System's Job: Receives the new custom setting data and verifies their API token is still valid

Key Components

When returning an Authentication response you will need to return these required fields:

  • full_name : Full name of the user

  • api_token : Token used to identify and authenticate user in future API calls to your web service

  • dashboard_code or dashboard : The code or object definition of the dashboard to use for a user

  • menu_code or menu : The code or object definition of the menu to use for a user

    NOTE: When returning a menu or menu_code, ensure that the specified menu contains a settings item. Otherwise, users will not be able to log out of the app. For more information, see our Menu Guide.

Data Sources

The data for this service comes directly from your backend systems. Your Authentication service is the "orchestrator" responsible for fetching and formatting the data (from your TMS, payroll, safety systems, etc.) that a user needs to build their mobile app experience.

Resources

API