Partner Portal API v1

The Partner Portal API provides programmatic access to your Holm Security portal data. Currently supports product usage, company management, and reporting periods for MSSP partners. All responses are JSON. Dates use YYYY-MM-DD format in the Europe/Stockholm timezone.

Base URL

https://portal-api.holmsecurity.com/v1

Content Type

All requests and responses use application/json; charset=utf-8.

Products

The API uses short product codes to identify Holm Security products:

Quick Start

Get up and running in minutes. Follow these steps to make your first API call.

curl -s -X POST https://portal-api.holmsecurity.com/v1/auth/session \
  -H "Content-Type: application/json" \
  -d '{"organizer_key": "hsp_org_your_organizer_key", "api_key": "hsp_your_api_key"}' | jq .

import requests

BASE_URL = "https://portal-api.holmsecurity.com/v1"

# Create a session with your key pair
session_resp = requests.post(f"{BASE_URL}/auth/session", json={
    "organizer_key": "hsp_org_your_organizer_key",
    "api_key": "hsp_your_api_key"
})
session = session_resp.json()
SESSION_TOKEN = session["session_token"]
print(f"Session created, expires at: {session['expires_at']}")

# Use session token for all subsequent requests
headers = {"Authorization": f"Session {SESSION_TOKEN}"}

const BASE_URL = "https://portal-api.holmsecurity.com/v1";

// Create a session with your key pair
const sessionRes = await fetch(`${BASE_URL}/auth/session`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    organizer_key: "hsp_org_your_organizer_key",
    api_key: "hsp_your_api_key"
  })
});
const session = await sessionRes.json();
const SESSION_TOKEN = session.session_token;
console.log(`Session created, expires at: ${session.expires_at}`);

// Use session token for all subsequent requests
const headers = { "Authorization": `Session ${SESSION_TOKEN}` };

curl -s https://portal-api.holmsecurity.com/v1/companies \
  -H "Authorization: Session pps_your_session_token" | jq .

resp = requests.get(f"{BASE_URL}/companies", headers=headers)
companies = resp.json()["results"]
for c in companies:
    print(f"{c['security_center_id']}  {c['company_name']}")

const res = await fetch(`${BASE_URL}/companies`, { headers });
const { results } = await res.json();
results.forEach(c => console.log(c.security_center_id, c.company_name));

# Latest usage for all companies, product SNS
curl -s "https://portal-api.holmsecurity.com/v1/usage/product?mode=latest&product=SNS" \
  -H "Authorization: Session pps_your_session_token" | jq .

# Peak usage for reporting period January 2026
curl -s "https://portal-api.holmsecurity.com/v1/usage/product?mode=period&reporting_year=2026&reporting_period=01&view=peaks" \
  -H "Authorization: Session pps_your_session_token" | jq .

# Daily usage for a specific company
curl -s "https://portal-api.holmsecurity.com/v1/usage/product?mode=period&reporting_year=2026&reporting_period=01&view=daily&security_center_id=SE-ARNXXXX" \
  -H "Authorization: Session pps_your_session_token" | jq .

import requests, time

# headers already set from step 2: {"Authorization": f"Session {SESSION_TOKEN}"}

# Latest usage for all companies
resp = requests.get(f"{BASE_URL}/usage/product", headers=headers,
                    params={"mode": "latest", "product": "SNS"})
data = resp.json()
print(f"Data as of: {data['as_of']}")
for row in data["results"]:
    print(f"  {row['security_center_id']}: {row['usage_value']}")

# Respect rate limit (1 req/sec)
time.sleep(1)

# Peak usage for a reporting period
resp = requests.get(f"{BASE_URL}/usage/product", headers=headers,
                    params={"mode": "period", "reporting_year": 2026,
                            "reporting_period": "01", "view": "peaks"})
peaks = resp.json()
for total in peaks.get("totals", []):
    print(f"  {total['product']}: peak sum = {total['total_peak_sum']}")

// headers already set from step 2: { "Authorization": `Session ${SESSION_TOKEN}` }

// Helper with rate-limit handling
async function apiGet(path, params = {}) {
  const url = new URL(`${BASE_URL}${path}`);
  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));

  const res = await fetch(url, { headers });
  if (res.status === 429) {
    const retryMs = (await res.json()).retry_after_ms || 1000;
    await new Promise(r => setTimeout(r, retryMs));
    return apiGet(path, params);  // retry once
  }
  return res.json();
}

// Latest usage
const latest = await apiGet("/usage/product", { mode: "latest", product: "SNS" });
console.log(`Data as of: ${latest.as_of}`);
latest.results.forEach(r =>
  console.log(`  ${r.security_center_id}: ${r.usage_value}`)
);

// Peak usage for a period
const peaks = await apiGet("/usage/product", {
  mode: "period", reporting_year: "2026",
  reporting_period: "01", view: "peaks"
});
peaks.totals.forEach(t =>
  console.log(`  ${t.product}: peak sum = ${t.total_peak_sum}`)
);

Common Workflows

Generate a monthly billing report

Fetch peak usage for the previous reporting period to calculate billing totals:

# 1. Check which periods are available
curl -s https://portal-api.holmsecurity.com/v1/reporting-periods/available \
  -H "Authorization: Session $SESSION_TOKEN" | jq .

# 2. Get peaks for the previous period (e.g. 2026-01)
curl -s "https://portal-api.holmsecurity.com/v1/usage/product?mode=period&reporting_year=2026&reporting_period=01&view=peaks" \
  -H "Authorization: Session $SESSION_TOKEN" | jq .

# The response includes "totals" with total_peak_sum per product

import requests, time

BASE_URL = "https://portal-api.holmsecurity.com/v1"
SESSION_TOKEN = "pps_your_session_token"  # from POST /v1/auth/session
headers = {"Authorization": f"Session {SESSION_TOKEN}"}

# 1. Find available periods
periods = requests.get(f"{BASE_URL}/reporting-periods/available",
                       headers=headers).json()["results"]
# Pick the most recent completed (non-partial) period
billing_period = next(p for p in periods if not p["is_partial"])
print(f"Billing period: {billing_period['year']}-{billing_period['period']}")
print(f"  Range: {billing_period['from']} to {billing_period['to']}")

time.sleep(1)  # respect rate limit

# 2. Fetch peak usage with totals
resp = requests.get(f"{BASE_URL}/usage/product", headers=headers,
    params={
        "mode": "period",
        "reporting_year": billing_period["year"],
        "reporting_period": billing_period["period"],
        "view": "peaks"
    })
data = resp.json()

# 3. Print billing summary
print("\nBilling Summary:")
for total in data["totals"]:
    print(f"  {total['product']} ({total['metric']}): "
          f"peak sum = {total['total_peak_sum']} "
          f"across {total['company_count']} companies")

# 4. Per-company breakdown
print("\nPer-company peaks:")
for peak in data["peaks"]:
    val = peak["peak_value"] if peak["peak_value"] is not None else "N/A"
    print(f"  {peak['company_name']} ({peak['security_center_id']}): "
          f"{peak['product']} = {val}")

Paginate through all companies

Use limit and offset to iterate through large result sets:

import requests, time

def get_all_companies(base_url, headers):
    """Fetch all companies, handling pagination and rate limits."""
    companies = []
    offset = 0
    limit = 100

    while True:
        resp = requests.get(f"{base_url}/companies", headers=headers,
                            params={"limit": limit, "offset": offset})

        if resp.status_code == 429:
            retry_ms = resp.json().get("retry_after_ms", 1000)
            time.sleep(retry_ms / 1000)
            continue

        data = resp.json()
        companies.extend(data["results"])

        if data["next"] is None:
            break

        offset += limit
        time.sleep(1)  # respect rate limit

    return companies

companies = get_all_companies(BASE_URL, headers)
print(f"Total companies: {len(companies)}")

async function getAllCompanies(baseUrl, headers) {
  const companies = [];
  let offset = 0;
  const limit = 100;

  while (true) {
    const url = `${baseUrl}/companies?limit=${limit}&offset=${offset}`;
    const res = await fetch(url, { headers });

    if (res.status === 429) {
      const { retry_after_ms } = await res.json();
      await new Promise(r => setTimeout(r, retry_after_ms || 1000));
      continue;
    }

    const data = await res.json();
    companies.push(...data.results);

    if (!data.next) break;
    offset += limit;
    await new Promise(r => setTimeout(r, 1000)); // rate limit
  }

  return companies;
}

const companies = await getAllCompanies(BASE_URL, headers);
console.log(`Total companies: ${companies.length}`);

Export daily usage to CSV

Pull daily usage for a period and write it to a CSV file:

import requests, csv, time

BASE_URL = "https://portal-api.holmsecurity.com/v1"
SESSION_TOKEN = "pps_your_session_token"  # from POST /v1/auth/session
headers = {"Authorization": f"Session {SESSION_TOKEN}"}

# Fetch daily usage for January 2026
all_rows = []
offset = 0

while True:
    resp = requests.get(f"{BASE_URL}/usage/product", headers=headers,
        params={
            "mode": "period",
            "reporting_year": 2026,
            "reporting_period": "01",
            "view": "daily",
            "limit": 1000,
            "offset": offset
        })

    if resp.status_code == 429:
        time.sleep(resp.json().get("retry_after_ms", 1000) / 1000)
        continue

    data = resp.json()
    all_rows.extend(data["results"])

    if data["next"] is None:
        break
    offset += 1000
    time.sleep(1)

# Write to CSV
with open("usage_2026_01.csv", "w", newline="") as f:
    writer = csv.DictWriter(f, fieldnames=[
        "date", "security_center_id", "company_name",
        "product", "metric", "usage_value"
    ])
    writer.writeheader()
    writer.writerows(all_rows)

print(f"Exported {len(all_rows)} rows to usage_2026_01.csv")

Authentication

The API uses a key pair + session authentication system. Partners authenticate with two keys to create a short-lived session, then use the session token for all API calls.

Key Pair

Each partner organization receives two keys from the Partner Portal settings:

Authentication Flow

1. Send a POST /v1/auth/session request with your organizer_key and api_key in the request body.
2. Receive a session token (format pps_...) in the response.
3. Include the session token in all subsequent API requests using the Authorization header:

Authorization: Session <session-token>

Session Properties

• Sessions are valid for 1 hour by default.
• Maximum 5 active sessions per organization. Exceeding this limit returns 409 Conflict.
• Sessions are locked to the IP address that created them (dynamic origin binding). Requests from a different IP will be rejected.

Origin Restrictions

API keys can optionally have allowed origins (IP addresses or domains) configured in portal settings. When configured, session creation requests are only accepted from those origins. Sessions are always locked to the IP that created them, regardless of whether allowed origins are configured.

Scopes

Sessions inherit the scopes assigned to the API key. A session may have multiple scopes.

Error Responses

401 Unauthorized — Missing, invalid, or expired session token

{
  "description": "Authentication credentials were not provided."
}

403 Forbidden — Valid session but missing required scope, IP mismatch, or company not accessible

{
  "description": "Permission denied",
  "errors": {
    "scope": ["Missing required scope: usage:read"]
  }
}

409 Conflict — Maximum sessions exceeded (when creating a new session)

{
  "description": "Session limit exceeded",
  "errors": {
    "session": ["Maximum of 5 active sessions per organization. Invalidate an existing session before creating a new one."]
  }
}

Rate Limiting

The API enforces a limit of 1 request per second per session.

If exceeded, the API returns HTTP 429 Too Many Requests:

{
  "description": "Rate limit exceeded",
  "retry_after_ms": 750
}

Response headers include:

Pagination

List endpoints support offset-based pagination:

Response Envelope

{
  "count": 0,
  "next": null,
  "previous": null,
  "results": []
}

Error Format

All error responses follow a consistent structure:

{
  "description": "Request failed",
  "errors": {
    "field": ["message"]
  }
}

Scope Requirements Summary