How-to use Scalar API Tool

Learn how to utilize the Scalar API Tool with Empirum REST API

+ More

Table of Contents

Overview Step 1: Open Scalar Step 2: Call the Auth Endpoint to Get a Token Step 3: Authenticate Scalar With That Token Step 4: Call a Production Endpoint (Example: Computer) Step 5: Explore Further Result

Overview

Scalar is the browser-based UI for trying out the Empirum REST API without writing any code. This guide walks through authenticating and calling your first endpoint.

This guide assumes you already completed the Empirum REST API Getting Started guide and have a Local Principal client_id / client_secret.

 

Scalar is available at /scalar/v1 (e.g. http://localhost:5057/scalar/v1) when the service runs in Development mode. The raw OpenAPI document is always available at /openapi/v1.json.

 

Step 1: Open Scalar

Navigate to http://localhost:5057/scalar/v1 (adjust host/port to match your installation).

Step 2: Call the Auth Endpoint to Get a Token

Every request needs a Bearer token. Find POST /api/auth/token in the endpoint list (usually under an "Auth" group) and select Test Request.

Fill in the request body (form-encoded) with your Local Principal credentials:

Field Value
grant_type client_credentials
client_id your Local Principal's client ID
client_secret your Local Principal's client secret

Click Send (or Test Request). The response looks like this:

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

The value you need is access_token. Copy the whole string (it's long — a JWT). expires_in tells you how many seconds it stays valid (typically 3600 = 1 hour); after that, repeat this step to get a fresh token.

 

Step 3: Authenticate Scalar With That Token

  1. Switch back to the Introduction section (usually the top entry in the left-hand navigation) — the Authentication option lives there, not on the endpoint you just called.
  2. In the Authentication section, select the Bearer type in the Auth Type dropdown.
  3. Paste the access_token value from Step 2 into the Bearer Token field (just the token itself, without the word "Bearer" in front — Scalar adds that automatically).

From now on, every request you send from Scalar automatically includes Authorization: Bearer <token>.

Step 4: Call a Production Endpoint (Example: Computer)

Find GET /api/computer in the endpoint list and select Test Request.

Optionally set skip/top for paging (defaults: skip=0, top=50), then click Send. You should get a 200 OK with a paged list of computers:

{
  "items": [ { "id": 4711, "hostname": "WORKSTATION-01", "...": "..." } ],
  "skip": 0,
  "top": 50,
  "totalCount": 128,
  "hasMore": true
}

If you instead get 401 Unauthorized, your token has expired or wasn't saved correctly — repeat Steps 2–3.

 

If you get 403 Forbidden, your Local Principal is missing the role required by that endpoint (e.g. computer.read) — assign it via the Permission Management web UI (/admin) or ask whoever manages roles in your organization.

 

Step 5: Explore Further

Every other endpoint works the same way once you're authenticated in Step 3 — no need to re-authenticate per endpoint. A few starting points:

  • POST /api/computer/search — search computers by hostname, domain, manufacturer, etc.
  • GET /api/group — list deployment groups
  • GET /api/packages — list software packages
  • POST /api/packages/search — search packages by name

Result

You can now authenticate in Scalar and call any Empirum REST API endpoint interactively from the browser — no code required.

You're ready to explore the full API surface using Scalar.

 

Related Articles