Zinc

Appearance

🚀 Getting Started with Zubie Zinc API ​

Zubie's Zinc API enables developers to build fleet and vehicle telematics apps by integrating with Zubie's platform. This guide walks you through:

  1. Setting up an OAuth client
  2. Understanding the OAuth2 flow with Zubie
  3. Using webhook events as triggers to call Zubie’s RESTful API

1. 🔐 Setting Up an OAuth Client ​

To securely access the Zubie API, you must first set up an OAuth client.

Steps: ​

  1. Create a Zinc Application
    👉 https://developer.zubie.com/manage-apps

  2. Register an Application:

    • Navigate to My Apps
    • Click Create New App
    • Fill in:
      • Application Name
      • Redirect URI (e.g., https://yourapp.com/oauth/callback)
      • Description

  3. Save your credentials:

    • You will receive a Client ID and Client Secret
    • Store these securely. You’ll need them for the OAuth2 exchange.

2. 🔄 Understanding the OAuth2 Flow ​

Zubie uses the Authorization Code Grant flow for OAuth2. More detailed Oauth2 instructions can be found here: https://developer.zubie.com/overview/authentication

Flow Overview: ​

Step 1: Redirect User to Zubie Authorization URL ​

http
https://login.zubiecar.com/authorize

The user will then be presented with an opportunity to login to their Zubie account and grant your application access to their Zubie data. After the user has granted your application access, they will be redirected back to your application/redirect url.

Query Parameters:

  • response_type=code
  • client_id=YOUR_CLIENT_ID
  • redirect_uri=YOUR_REDIRECT_URI
  • state=xyz123 (optional)

Example:

https://login.zubiecar.com/authorize?response_type=code&client_id=abc123&redirect_uri=https://yourapp.com/oauth/callback

Step 2: Handle Redirect with Authorization Code ​

Zubie will redirect the user back to your app:

https://yourapp.com/oauth/callback?code=AUTH_CODE

Step 3: Exchange Code for Access Token ​

POST

http
https://login.zubiecar.com/oauth/token

Body (x-www-form-urlencoded):

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=YOUR_REDIRECT_URI
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Response:

json
{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN"
}

Store both access_token and refresh_token securely. These credentials grant access to protected data and must never be exposed, especially in client-side code. For web applications, prefer HttpOnly and Secure cookies or server-side storage.

3. 🔔 Use Webhooks to get real time data without having to poll ​

Webhooks allow your app to respond to real-time events (e.g., trip start, engine status).

Webhook playloads generally have enough detail to process without needing addition API calls, but webhooks can also be used to trigger additional API calls, if necessary.

Step 1: Create a Webhook Listener ​

Set up a public HTTPS endpoint to receive POST requests:

https://yourapp.com/webhooks/zubie

Step 2: Register Webhook with Zubie ​

Configure the webhook URL and select the events you wish to recieve for your app at https://developer.zubie.com/manage-apps. The webhook URL is the endpoint on your system that Zubie will send payloads.

Specify:

  • Your webhook URL
  • Events of interest (trip_start, location_change, etc.)

Detailed instructions can be found here: https://developer.zubie.com/webhooks/enabling-webhooks

Step 3: Handle Webhook Events ​

Webhook payload example:

json
{
    "user_id": "vxXDeLFxMPHEUfNcG8BmLB",
    "account_id": "CrTLZuPfq8T4SG4UKWKqKV",
    "user_key": "sample_user_key",
    "account_key": "sample_account_key",
    "device": {
        "key": "agpzfnp1YmllLXFhciILEgZEZXZpY2UiFmFHWTRXdkFGcDhVYmtjRE5SNlg0QnkM",
        "serial": "182400007"
    },
    "event": "device_unplug",
    "timestamp": "2019-02-20T19:00:52-05:00",
    "vehicle": {
        "battery_level": 9.9,
        "fuel_level": 4,
        "key": "agpzfnp1YmllLXFhcjcLEgdBY2NvdW50IhZDclRMWnVQZnE4VDRTRzRVS1dLcUtWDAsSA0NhciILTjR1NFBNY0RycDQM",
        "nickname": "Pearl",
        "vehicle_location": {
            "point": {
                "lat": 32.88288,
                "lon": -80.036206
            }
        },
        "vin": "JM3TCADY5G0107976"
    }
}

4. ⚙️ Calling the Zinc REST API ​

Use the access_token to make authenticated API requests.

Example: Get Devices ​

GET

http
https://api.zubie.com/api/v1/devices

HEADER

http
Authorization: Bearer ACCESS_TOKEN

There are several API endpoints that offer access to a variety of Zubie account data. You can find more information on API endpoints in the reference section of the documentation: https://developer.zubie.com/reference/account

🔁 Refreshing Access Tokens ​

Access tokens expire (typically after 1 hour). Use the refresh_token:

POST

http
https://login.zubiecar.com/oauth/token

Body:

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

✅ Summary Flow ​

plaintext
[User Authorizes App] 
      ↓
[App gets Access Token via OAuth2] 
      ↓
[Zubie Sends Webhook on Event]
      ↓
[App Receives Webhook, Triggers API Call]
      ↓
[App Processes and Responds to Event]