> 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/collections.md).

# Using Hiboo API with Postman

Set up Postman to efficiently test and explore the Hiboo API with automated authentication.

## What You'll Achieve

By the end of this guide, you'll have:

* A fully configured Postman collection with all Hiboo API endpoints
* Automatic token management (no manual copy-paste)
* Pre-configured environment variables
* Working authentication flow

> **Alternative Tools**: This guide focuses on Postman, but you can use similar tools like [Insomnia](https://insomnia.rest/) or [Hoppscotch](https://hoppscotch.io/) with the same OpenAPI file.

## Step 1: Download Required Files

1. **Download our OpenAPI specification**: [openapiv2.yml](https://spec.hiboo.io/openapiv2.yml)
2. **Install Postman**: [Download here](https://www.postman.com/downloads/) or use the web version

## Step 2: Import the API Collection

1. **Open Postman** and click **"Import"**

   <figure><img src="/files/d4SqOrH7CDbXyEFFyhUB" alt="Import button in Postman"><figcaption></figcaption></figure>
2. **Upload the OpenAPI file** and select **"Postman Collection"**

   <figure><img src="/files/rCFLStwnFiEiiyvmrb8i" alt="Choose Postman collection option"><figcaption></figcaption></figure>
3. **Verify import** - You should see "Hiboo API" collection in your sidebar

## Step 3: Configure Authentication Variables

1. **Prepare your API Credentials**, if you have no API credential, go to the [Hiboo API](https://app.hiboo.io/destinations), you will be able to define an `apiName` and an `apiKey` will be generated.
2. **Open collection settings** by clicking on your collection name → **Variables** tab
3. **Create these three variables**:

   <figure><img src="/files/WUruVbxrxOvkexfU4Js1" alt="Collection variables configuration"><figcaption></figcaption></figure>

   | Variable Name    | Initial Value   | Current Value   | Description                           |
   | ---------------- | --------------- | --------------- | ------------------------------------- |
   | `x-access-token` | *(leave empty)* | *(leave empty)* | Auto-updated after login              |
   | `apiName`        | *(leave empty)* | `your-api-name` | Your API account name generated in 1. |
   | `apiKey`         | *(leave empty)* | `your-api-key`  | Your API key generated in 1.          |

   > **Security Note**: Only set the "Current Value" for `apiName` and `apiKey`. Be careful before setting "Initial Value" for sensitive data ([See Postman documentation for more details](https://learning.postman.com/docs/sending-requests/variables/variables/#initial-and-current-values)).
4. **Save** your variables

## Step 4: Set Up Collection-Level Authentication

1. **Go to Authorization tab** in your collection settings
2. **Select "API Key"** and configure:

   * **Key**: `x-access-token`
   * **Value**: `{{x-access-token}}`
   * **Add to**: `Header`

   <figure><img src="/files/69wGwdiHOONnkYU15KEf" alt="Collection authentication setup"><figcaption></figcaption></figure>

## Step 5: Configure Automatic Login

1. **Find the `/login` endpoint** in your collection
2. **Set up the request body** with your variables:

   ```json
   {
     "name": "{{apiName}}",
     "apiKey": "{{apiKey}}"
   }
   ```

   <figure><img src="/files/QRxnk0ANjy5ynKhyiZrf" alt="Login request body configuration"><figcaption></figcaption></figure>
3. **Add the auto-token script** in the **Tests** tab:

   ```javascript
   // Auto-update token after successful login
   if (pm.response.code === 200) {
       const responseData = pm.response.json();
       pm.collectionVariables.set("x-access-token", responseData.token);
       console.log("Token updated successfully");
   } else {
       console.log("Login failed:", pm.response.text());
   }
   ```

   <figure><img src="/files/Vx5gisQLahP0oqE6Nfsq" alt="Login post-request script"><figcaption></figcaption></figure>

## Step 6: Test Your Setup

1. **Execute the login request** by clicking **Send**
2. **Verify success** - You should see a response like:

   ```json
   {
     "id": 42,
     "email": "api@hiboo.io",
     "admin": false,
     "firstName": "John",
     "lastName": "Doe",
     "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
   }
   ```
3. **Check token was saved** - Look in your collection variables; `x-access-token` should now have a value
4. **Test an authenticated endpoint**:

   * Open `/v2/fleet/equipments`
   * Ensure **Authorization** is set to **"Inherit auth from parent"**
   * Click **Send**

   <figure><img src="/files/hVHcvAq27USNzrLOZvUK" alt="Inherit authentication setting"><figcaption></figcaption></figure>
5. **Verify API response**:

   <figure><img src="/files/NA4LNcMgtvREDry2AqDc" alt="Successful API request test"><figcaption></figcaption></figure>