> For the complete documentation index, see [llms.txt](https://docs.hiboo.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hiboo.io/guides/getting-started/authenticate-test.md).

# 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](https://app.hiboo.io/destinations). 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:

{% openapi src="<https://spec.hiboo.io/openapiv2.yml>" path="/login" method="post" %}
<https://spec.hiboo.io/openapiv2.yml>
{% endopenapi %}

## Complete Authentication Flow

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

{% stepper %}
{% step %}

#### Login Request

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

{% endstep %}

{% step %}

#### Login Response

```json
{
  "id": 42,
  "email": "api@hiboo.io",
  "admin": false,
  "firstName": "John",
  "lastName": "Doe",
  "token": "eyJhbGciOiJIfkdFVHUREIsInR5cCI6IkpXVCJ9.xxXxXXX6OXXxXxxxx3XxXXXXXx6XxXxXxxxxXX6XXX3Xxx2XxX5OXwiXXxxXxxxXXx0XxX2Xxx4xX.Ylm61gfwIgGx2bQLjtq4UkqF1MOak9y8REsVfn1GtoQ"
}
```

{% endstep %}

{% step %}

#### Use Your Token in API Calls

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

```bash
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:**

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

{% endstep %}

{% step %}
**Success!** If you see a response like this, your authentication is working correctly and you're ready to explore the API.
{% endstep %}
{% endstepper %}

## 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