Getting started

Goal

This page takes you from zero to a first working check:

log in and retrieve your API token;
create a host;
attach a check to it;
run the check and read its result.

The examples use the fictitious host web-prod-01 (10.0.0.12).

1. Log in

Open the portal in your browser:

Production: https://portal.secumon.secuaas.dev

Authenticate with your account. Once logged in, you reach your organization's dashboard.

Retrieving your token for the API

All API requests are authenticated with a Bearer token tied to your session. Once logged in to the portal, retrieve your session token and place it in the Authorization header of every request:

Authorization: Bearer <your-token>

The API base URL is:

Production: https://api.secumon.secuaas.ovh/api/v2
Development: https://api.secumon.secuaas.dev/api/v2

Confirm that everything works by calling the status overview:

curl -s https://api.secumon.secuaas.ovh/api/v2/status \
  -H "Authorization: Bearer $SECUMON_TOKEN"

{
  "hosts":  { "total": 0, "active": 0 },
  "checks": { "total": 0, "enabled": 0, "failing": 0, "failing_pct": 0 },
  "active_incidents": 0,
  "active_storms": 0,
  "workers": 1
}

2. Create your first host

A host represents a target to monitor. It does not perform any measurement on its own: it serves as the anchor point to which you attach checks.

From the portal

Open the Hosts section.
Click Add a host.
Fill in a name (web-prod-01) and a hostname or IP (10.0.0.12).
Optionally add tags (e.g. env: prod, role: web).
Confirm.

Creation reserved for the owner and admin roles.

Through the API

curl -s -X POST https://api.secumon.secuaas.ovh/api/v2/hosts \
  -H "Authorization: Bearer $SECUMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-prod-01",
    "hostname": "10.0.0.12",
    "host_type": "server",
    "tags": { "env": "prod", "role": "web" }
  }'

{
  "id": "8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f",
  "org_id": "3886d3da-3d77-4a1e-9b2c-aabbccddeeff",
  "name": "web-prod-01",
  "hostname": "10.0.0.12",
  "host_type": "server",
  "tags": { "env": "prod", "role": "web" },
  "is_active": true,
  "created_at": "2026-06-23T12:00:00Z",
  "updated_at": "2026-06-23T12:00:00Z"
}

Note the returned id: it identifies the host in all subsequent calls.

3. Add a check

A check is a probe attached to a host. Let's start with a ping: it measures latency and reports whether the host responds.

From the portal

Open the Checks section (or the host's detail view).
Click Add a check.
Choose the host web-prod-01 and the ping type.
Specify the target in the configuration (host: 10.0.0.12).
Set the interval (default 60 s) and the timeout (default 30 s).
Confirm.

Creation reserved for the owner and admin roles.

Through the API

curl -s -X POST https://api.secumon.secuaas.ovh/api/v2/checks \
  -H "Authorization: Bearer $SECUMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "host_id": "8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f",
    "name": "ping web-prod-01",
    "check_type": "ping",
    "config": { "host": "10.0.0.12" },
    "interval_sec": 60,
    "timeout_sec": 10
  }'

{
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "org_id": "3886d3da-3d77-4a1e-9b2c-aabbccddeeff",
  "host_id": "8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f",
  "name": "ping web-prod-01",
  "check_type": "ping",
  "config": { "host": "10.0.0.12" },
  "interval_sec": 60,
  "timeout_sec": 10,
  "retries": 0,
  "enabled": true,
  "created_at": "2026-06-23T12:01:00Z",
  "updated_at": "2026-06-23T12:01:00Z"
}

The check is now scheduled: it will run automatically every 60 seconds on a worker.

4. Run it and read the result

Run the check immediately

Without waiting for the next cycle, you can force a run:

curl -s -X POST \
  https://api.secumon.secuaas.ovh/api/v2/checks/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/run \
  -H "Authorization: Bearer $SECUMON_TOKEN"

{
  "queued": true,
  "check_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "run_id": "c0ffee00-1234-4abc-9def-0123456789ab"
}

Read the latest result

curl -s \
  https://api.secumon.secuaas.ovh/api/v2/checks/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/last-result \
  -H "Authorization: Bearer $SECUMON_TOKEN"

{
  "check_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "host_id": "8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f",
  "time": "2026-06-23T12:01:30Z",
  "status": 0,
  "latency_ms": 1.5,
  "output": "pong 1.5ms",
  "error_msg": ""
}

The status field follows a numeric convention common to all checks:

`status`	Meaning
`0`	OK
`1`	Degraded
`2`	Critical
`3`	Unknown

A result of 0 confirms that web-prod-01 responds correctly.

What's next?

Discover the 7 check types and their options on the Checks page.
Configure your notifications with Alert policies and On-call.
Communicate the state of your services with a Status page.
Full endpoint reference: API.

On this page