This page outlines the high-level design and usage patterns of the Gridio Connect API. Most of the integration work should be performed through backend-to-backend communication between your services and Gridio.

<aside> 💡 TL;DR: Use backend-to-backend for all API calls (OAuth2 client credentials). Frontend is only for device onboarding via Gridio Connect UI. Use webhooks for real-time events instead of polling.

</aside>

Backend connectivity offers a more secure and reliable environment — ideal for error handling and scalability.

The only exception to this rule is during initial device integration, which requires secure user interaction via the frontend. The reasons are twofold, for secure authentication OEMs sometimes require solving captchas (not easily done in the backend for obvious reasons) and second, if possible, the user credentials should move between different services as little as possible. If one could authenticate via OAuth2 code flow and pass only the received code to the backend, then this is preferred to passing username and password to the backend.

🏗️ Architecture Overview

Three integration paths:

  1. Device onboarding — Frontend → Gridio Connect UI (short-lived customer token)
  2. All other API calls — Your Backend → Gridio (OAuth2 client credentials)
  3. Real-time events — Gridio → Your Backend via webhooks (x-api-key header)

📋 Quick Reference: What Goes Where

🔗 Backend-to-Backend Integration

Your system should handle all core interactions with Gridio via the OAuth2 client credentials flow. These tokens provide access to your entire customer and device fleet and must be managed securely.

🔒 Do not use backend tokens in any frontend application.