Overview

This guide walks through generating a ready-to-use Postman collection from the Empirum REST API's OpenAPI document, configuring Bearer-token authorization once at collection level, and running an authorized sample request.

Prerequisites

• Postman (desktop or web) — free tier is sufficient.
• The URL of your Empirum REST API instance, e.g. https://empirum-api.example.com (referred to as base URL below).
• API credentials (client_id / client_secret) with the roles needed for the endpoints you want to call (e.g. computer.read). Ask your Empirum administrator if you don't have them yet.

Step 1: Import the OpenAPI Document as a Collection

The API serves its OpenAPI 3 document at:

/openapi/v1.json

In Postman:

1. Import (top-left) → paste the URL https://empirum-api.example.com/openapi/v1.json (or download the JSON in a browser and drop the file into the import dialog).
2. In the import preview, select Postman Collection as the import target (not "OpenAPI 3.0 with a Test Suite" — plain collection is enough).
3. Under View Import Settings, set Folder organization to Tags — endpoints are then grouped by area (Computer, Group, Packages, …).
4. Click Import.

Postman creates a collection with one request per endpoint, path/query parameters pre-filled as variables, and example bodies for POST/PATCH requests.

Base URL

The import creates a collection variable baseUrl. Open the collection → Variables tab → set:

Step 2: Configure Authorization

Every endpoint (except token issuance) requires Authorization: Bearer <jwt>. Configure this once at collection level; all requests inherit it.

Step 2a: Get a Token — Request

The token endpoint is POST {{baseUrl}}/api/auth/token (RFC 6749 client_credentials, form-encoded, no authentication required). The imported collection already contains this request under the Auth folder; verify it looks like this:

• Method: POST, URL: {{baseUrl}}/api/auth/token
• Body → x-www-form-urlencoded:

Response:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

expires_in is in seconds — re-run the token request when it lapses.

Step 2b: Store the Token Automatically

Add this to the token request's Scripts → Post-response tab so every successful token call updates a collection variable:

const json = pm.response.json();
pm.collectionVariables.set("accessToken", json.access_token);

Step 2c: Use the Token at Collection Level

Collection → Authorization tab:

• Auth Type: Bearer Token
• Token: {{accessToken}}

Leave every individual request's Authorization set to Inherit auth from parent (the import default).

Step 3: Sample Request

1. Run the token request from Step 2a once — the post-response script fills {{accessToken}}.
2. Open any read endpoint, e.g. GET {{baseUrl}}/api/computer?skip=0&top=10 (requires the computer.read role).
3. Send. Expected: 200 OK with a paged result:

{
  "items": [ { "...computer fields..." : "..." } ],
  "totalCount": 1234,
  "skip": 0,
  "top": 10
}

Troubleshooting

Keeping the Collection Up to Date

The collection is a snapshot of the OpenAPI document. After an API update, re-import the URL and re-apply Steps 1–2c (base URL variable, post-response script, collection-level authorization).