Authenticate & Test

Authentication Overview

To use the Hiboo REST API you must first have an existing account on Hiboo. Once you have an account, you can request for API access to our Hiboo team if you don't have access. After getting the API permission you are free to use the Hiboo REST API for your needs.

Our authentication system uses x-access-token for validating requests. You can get the token after successful login.

API Credentials

You can create multiple API credentials on the application. Here's a breakdown of what makes a credential:

• API Name: Must be unique. You define it and your organization name is added as a suffix {you choice}_{organization name}

• API Key: Auto generated when you create a credential, you can rotate it on the application

• Workspace: Pick the workspace your credential will have access to.

• Role: Admin (can update data) or Viewer (read-only)

Never share your secret keys. Keep them guarded and secure.

Login to Get Your Token

Use the login endpoint below to authenticate and receive your access token:

Authenticate on the API

post

Authenticate on the API with your credentials to get a token that you can use in your requests.

Body

namestringOptionalExample: api_company

apiKeystringOptionalExample: 2ddd4027-c779-4b7c-80fe-8661c92c35ff

Responses

200

Token to use in the other API calls

application/json

401

Unable to authenticate the token

application/json

post

HTTPcURLJavaScriptPython

POST /login HTTP/1.1
Host: api.hiboo.io
Content-Type: application/json
Accept: */*
Content-Length: 70

{
  "name": "api_company",
  "apiKey": "2ddd4027-c779-4b7c-80fe-8661c92c35ff"
}

{
  "id": 42,
  "email": "[email protected]",
  "admin": false,
  "firstName": "John",
  "lastName": "Doe",
  "token": "eyJhbGciOiJIfkdFVHUREIsInR5cCI6IkpXVCJ9.xxXxXXX6OXXxXxxxx3XxXXXXXx6XxXxXxxxxXX6XXX3Xxx2XxX5OXwiXXxxXxxxXXx0XxX2Xxx4xX.Ylm61gfwIgGx2bQLjtq4UkqF1MOak9y8REsVfn1GtoQ"
}

Complete Authentication Flow

Here's a complete example of logging in and making your first API call:

1

Login Request

curl -X POST "https://api.hiboo.io/login" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api_company",
    "apiKey": "2ddd4027-c779-4b7c-80fe-8661c92c35ff"
  }'

2

Login Response

{
  "id": 42,
  "email": "[email protected]",
  "admin": false,
  "firstName": "John",
  "lastName": "Doe",
  "token": "eyJhbGciOiJIfkdFVHUREIsInR5cCI6IkpXVCJ9.xxXxXXX6OXXxXxxxx3XxXXXXXx6XxXxXxxxxXX6XXX3Xxx2XxX5OXwiXXxxXxxxXXx0XxX2Xxx4xX.Ylm61gfwIgGx2bQLjtq4UkqF1MOak9y8REsVfn1GtoQ"
}

3

Use Your Token in API Calls

For all subsequent API requests, include your token in the x-access-token header:

curl -X GET "https://api.hiboo.io/v2/fleet/equipments?limit=1" \
  -H "x-access-token: eyJhbGciOiJIfkdFVHUREIsInR5cCI6IkpXVCJ9.xxXxXXX6OXXxXxxxx3XxXXXXXx6XxXxXxxxxXX6XXX3Xxx2XxX5OXwiXXxxXxxxXXx0XxX2Xxx4xX.Ylm61gfwIgGx2bQLjtq4UkqF1MOak9y8REsVfn1GtoQ" \
  -H "Content-Type: application/json"

Expected Response:

{
  "data": {
    "total": 1,
    "rows": [
      {
        "id": 1,
        "name": "D8000-1",
        "make": "Caterpillar",
        "model": "8000",
        "serialNumber": "YVR001988"
      }
    ]
  }
}

4

Success! If you see a response like this, your authentication is working correctly and you're ready to explore the API.

Troubleshooting Authentication

Common Issues

401 Unauthorized Error

• Check that your API key is correct

• Verify that API access has been granted to your account

• Ensure you're using the correct environment (sandbox vs production)

Token Expired

• Tokens have a limited lifetime for security

• Login again to get a new token

• Consider implementing automatic token refresh in your applications

Invalid Token Format

• Ensure you're using the x-access-token header (not Authorization)

• Check that there are no extra spaces or characters in your token

Token Management

Token Expiration

• Tokens have a limited lifetime for security

• You'll receive a 401 Unauthorized response when your token expires

• Simply login again to get a new token

Token Security Best Practices

• Store tokens securely - Never hardcode them in your source code

• Use environment variables for token storage

• Implement token refresh in your applications

• Monitor for 401 errors and handle re-authentication