Empirum REST-API

The Empirum REST API provides programmatic access to Matrix42 Empirum. Customers and partners can use it to integrate Empirum with third-party systems (ITSM, CMDB, SIEM, reporting platforms, orchestration tools) and to automate recurring administrative tasks such as software rollouts, reinstallations, patch remediation, inventory exports and fleet health checks.

See the dedicated articles for more details.

Overview

Each Cloud instance runs at its own host, https://empirumXXX.m42cloud.com. The instance's first administrator is an Entra (Azure AD) user following the naming convention empcloudXXX-1@m42cloud.com. This account is assigned during provisioning and already holds the admin.manage role.

To let your own applications or scripts call the REST API, the administrator signs in to the Permission Management web UI at https://empirumXXX.m42cloud.com/admin and creates a Local Principal there: a client_id / client_secret pair with a specific set of roles. Your application then exchanges that pair for a short-lived access token and calls the REST API with it, the same way as any on-premises client.

Signing in to Permission Management

1. Open https://empirumXXX.m42cloud.com/admin in a browser.
2. Sign in with your Entra account (e.g. empcloudXXX-1@m42cloud.com).

Creating a Local Principal

1. In the left navigation, open Local Principals.
2. Click Create Principal.
3. Fill in the New Client Credential form:
   • Description: optional free text to identify the client later (e.g. "Ticketing system integration").
   • Expires: enter a number of days, or pick a date. Leave empty for no expiry. An expired credential is rejected at POST /api/auth/token the same as a revoked one.
   • Roles: check every role this application actually needs (least privilege). Select all selects every role except admin.manage, which can never be assigned to a Local Principal in the Cloud.
4. Click Create.

A green panel appears: "New credential created — save the secret now, it will not be shown again." It shows the generated Client ID and Secret, each with a Copy button.

Choosing roles

Assign only the roles your application actually calls. Never include admin.manage; it is reserved for Entra administrators.

Using the credential in your application

Your application exchanges the client_id / client_secret for a Bearer token exactly like an on-premises client. See PowerShell examples for the full set of helper functions and examples.

Minimal PowerShell example:

$tokenBody = @{
    grant_type    = 'client_credentials'
    client_id     = '<the Client ID from the panel above>'
    client_secret = '<the Secret from the panel above>'
}
# Replace XXX with your instance
$token = Invoke-RestMethod -Method Post `
    -Uri 'https://empirumXXX.m42cloud.com/api/auth/token' `
    -ContentType 'application/x-www-form-urlencoded' `
    -Headers @{ 'api-version' = '1' } `
    -Body $tokenBody

# $token.access_token is a Bearer JWT, valid for $token.expires_in seconds
Invoke-RestMethod -Uri 'https://empirumXXX.m42cloud.com/api/system' `
    -Headers @{ Authorization = "Bearer $($token.access_token)"; 'api-version' = '1' }

Managing an existing Local Principal

On the Local Principals page, each row shows Client ID, Description, Roles, Status (Active / Expired / Revoked), Expires, and Created date, with the following per-row actions:

• Edit: change the description, roles, or expiry. Does not require or reveal the secret.
• Revoke / Restore: immediately block or re-enable the credential without deleting it.
• Delete: permanently remove the credential. Any application still using it will get 401 on its next token request.