Overview

This guide walks through the fastest path from the unzipped Empirum REST API package to your first successful API call — creating the database tables, installing the Windows service, creating a Local Principal, and calling the API.

Step 1: Create the Database Tables (Empirum DBUtil)

Run dbscripts\PrepareRestApiTables.sql against your Empirum database via Empirum DBUtil. This creates the RestApi_* tables used for principal (API key) and role management.

Step 2: Install the Windows Service

Run Install-WindowsService.ps1 as Administrator, pointing it at the same database. This registers and starts the EmpirumRestApi Windows service and seeds a one-time ADMIN local principal (client_id + client_secret, admin.manage role only) into the RestApi_* tables created in Step 1.

Run Get-Help .\Install-WindowsService.ps1 -Full for every available option (HTTPS certificates, OIDC, firewall, retry tuning, etc.).

Unless you pass -HttpPort or -HttpsPort, the service listens on plain HTTP port 5057 by default.

Windows Authentication, Service Running Under a Specific Account

-SqlServer/-Database alone assume Windows Integrated auth — the service account authenticates to SQL directly, so that account needs access to the database. By default the service runs as LocalSystem; to run it as a domain user or a group Managed Service Account (gMSA) instead, add -ServiceAccount.

Domain user (also needs -ServicePassword):

.\Install-WindowsService.ps1 -SqlServer  -Database  `
    -ServiceAccount 'CONTOSO\svc-empirum' -ServicePassword ''

gMSA (account name ends with $ — no password needed, Windows manages it):

.\Install-WindowsService.ps1 -SqlServer  -Database  `
    -ServiceAccount 'CONTOSO\svc-empirum$'

SQL Login, Service Running as LocalSystem

If the database is on a separate server and Windows Integrated auth isn't an option, add -SqlUser/-SqlPassword for a SQL login instead. Leave -ServiceAccount unset to keep the service running as LocalSystem.

.\Install-WindowsService.ps1 -SqlServer  -Database  `
    -SqlUser  -SqlPassword ''

This builds the runtime connection string from the four parts; the ADMIN seed step reuses the same connection. Alternatively, pass a fully custom connection string directly with -ConnectionString instead of the individual -SqlServer/-Database/-SqlUser/-SqlPassword parts.

The console output also prints the URL of the Permission Management web UI. With the default port (no -HttpPort/-HttpsPort given):

Permission Management (web UI): http://localhost:5057/admin

Step 3: Create a Local Principal for API Access

Open the printed /admin URL in a browser and sign in with the ADMIN client_id/client_secret from Step 2. Under Local Principals, create a new Local Principal and assign it the roles your integration needs (e.g. computer.read, package.read). Save the generated client_id and client_secret — the secret is shown once, at creation time.

Step 4: Call the API

Use the new Local Principal's client_id/client_secret with the sample script:

.\powershell-samples\Invoke-EmpirumRestApiSample.ps1 -ClientId  -ClientSecret 

It authenticates against POST /api/auth/token, then lists a few computers, groups, and packages as a smoke test.

Explore the rest of the API interactively at /scalar/v1, or via the OpenAPI document at /openapi/v1.json.

Step 5: Explore the API — the OpenAPI Document

The complete documentation of the REST API is not a PDF or a website — it is the OpenAPI document the service publishes about itself at:

http://localhost:5057/openapi/v1.json

OpenAPI (formerly known as Swagger) is the industry-standard, machine-readable description format for REST APIs. The document lists everything the API offers:

• Every endpoint (route/URL) and its HTTP method (GET, POST, PATCH, PUT)
• All parameters (path, query, paging) and request/response body schemas with examples
• The roles required to call each endpoint
• How authentication works (Bearer token)

Because the format is standardized, many tools can consume it directly — you rarely need to read the JSON yourself. Typical uses:

• Browse & try out: the built-in Scalar UI at /scalar/v1 renders the document as an interactive reference where you can send real requests from the browser.
• Postman: import the document URL and get a ready-made collection with one pre-filled request per endpoint.
• Code generation: generators like Kiota, NSwag, or openapi-generator create typed client libraries (C#, PowerShell, Python, TypeScript, …) from the same document.

The document always matches the installed API version — whenever the API changes, the OpenAPI document changes with it.

Result

You now have the EmpirumRestApi Windows service running, a Local Principal with scoped API access, and a successful smoke-test call against /api/auth/token. From here, use the Scalar UI or the OpenAPI document to explore and build against the full API surface.