Skip to main content

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.

Every request needs a token, which you get from the login endpoint. Send it in the Authorization header as Bearer <token>, or in the x-access-token header.

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:

POST /login · Authenticate on the API

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": "api@hiboo.io",
      "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 Authorization header as Bearer <token>. The x-access-token header works too.

    curl -X GET "https://api.hiboo.io/v2/fleet/equipments?limit=1" \
      -H "Authorization: Bearer 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​

403 No token provided

  • The request has no token: add the Authorization: Bearer or x-access-token header

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

  • Send the token as Authorization: Bearer <token> or x-access-token: <token>. If a request has both headers, the API uses the Authorization header
  • 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