---
title: "Create SSH Monitor"
description: "Creates a new SSH monitor."
---

`POST /api/ssh-monitors`

## Authentication

Requires a valid session.

- Header: `Authorization: Bearer <token>`

## Request Body

```json
{
  "customerId": "11111111-1111-4111-8111-111111111111",
  "name": "Bastion Host",
  "hostname": "ssh.deinkunde.com",
  "port": 22,
  "status": "active",
  "checkInterval": 60,
  "timeoutSeconds": 30,
  "sshConfig": {
    "username": "root",
    "password": "password",
    "privateKey": "-----BEGIN OPENSSH PRIVATE KEY-----..."
  }
}
```

### Fields

- `customerId` (number | string, required)
  - Accepts either the internal numeric customer ID or the public customer UUID.
- `name` (string, required)
- `hostname` (string, required)
  - Must be a hostname only (no protocol like `https://`, no path like `/ssh`).
- `port` (number | null, optional)
  - If omitted or `null`, the worker defaults to port `22`.
- `status` (string, optional)
  - Allowed: `active`, `maintenance`, `disabled`, `paused`, `inactive`
- `checkInterval` (number, optional)
- `timeoutSeconds` (number, optional)
- `checkMode` (string, optional)
  - Allowed: `protocol`, `tcp`. Defaults to `protocol`.
  - In `tcp` mode the monitor performs a bare TCP port-reachability check: `sshConfig` is not required and is not stored. In `protocol` mode the full SSH login/handshake check runs (existing behavior).
- `sshConfig` (object, optional)
  - Stored as the monitor's `config` JSON.
  - Required (username + password or privateKey) unless `checkMode` is `tcp`.

### `sshConfig` (worker-supported keys)

- `username` (string)
  - If omitted, the worker uses `anonymous`.
- `password` (string)
- `privateKey` (string)

## cURL

```bash
curl -X POST "https://YOUR_DOMAIN/api/ssh-monitors" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "11111111-1111-4111-8111-111111111111",
    "name": "Bastion Host",
    "hostname": "ssh.deinkunde.com",
    "port": 22,
    "status": "active",
    "checkInterval": 60,
    "timeoutSeconds": 30,
    "sshConfig": { "username": "root", "password": "password" }
  }'
```

## Response

```json
{
  "id": 300,
  "organizationId": 1,
  "customerId": 10,
  "name": "Bastion Host",
  "hostname": "ssh.deinkunde.com",
  "port": 22,
  "status": "active",
  "checkInterval": 60,
  "timeoutSeconds": 30,
  "notificationEmail": null,
  "notificationPhoneNumber": null,
  "lastCheckedAt": null,
  "createdAt": "2026-02-26T12:00:00.000Z",
  "updatedAt": "2026-02-26T12:00:00.000Z",
  "config": {
    "username": "root",
    "password": "password"
  },
  "sshConfig": {
    "username": "root",
    "password": "password"
  }
}
```

## Errors

- `400` Invalid hostname or invalid request body
- `400` Invalid Customer identifier
- `401` Unauthorized
- `403` Forbidden (e.g. `readonly` or global supporter)