Sentinel Savant Rubi Bridge

Bridge & App microsite link: [Savant Sentinel Pro](https://savantcyprus.com/sentinel-pro.html)

Protocol and API Specification (v4.3 Beta / v4.3b1-pro)

Date: 2026-04-01 Runtime reference: savant_network_sentinel_clean_rubi_bridge_v4_3b1_pro.rb

1. Transport and Protocol Baseline

1.1 Transport

Protocol: HTTP/1.1 JSON APIs (WEBrick server)
Modes:

- HTTP (non-TLS) - HTTPS (TLS enabled via bridge flags)

Defaults:

- bind host: 0.0.0.0 - port: 42042

1.2 Content Model

Request body: application/json (UTF-8)
Response body: application/json except binary audio preview endpoint
Authentication: bearer token in Authorization header

1.3 Authentication Header


Authorization: Bearer <token>

1.4 Error Envelope (Typical)


{ "error": "forbidden" }

Additional fields may appear:

pairing_state
password_policy
role_warning
endpoint-specific metadata

2. Endpoint Inventory

The bridge root endpoint exposes a route list, but note that /api/v1/home/integrator-access is also implemented and should be considered part of the official v4.3 beta surface.

2.1 Public/Bootstrap Endpoints

| Endpoint | Method | Auth | Purpose | |---|---|---|---| | / | GET | no | bridge metadata and endpoint discovery | | /health | GET | no | runtime health, PID, session count, state counts | | /api/v1/auth/login | POST | no | login and session issuance |

2.2 Authentication and Session Endpoints

| Endpoint | Method | Auth | Purpose | |---|---|---|---| | /api/v1/auth/me | GET | yes | current session metadata | | /api/v1/auth/change-password | POST | yes | password rotation/change |

2.3 Governance and Pairing Endpoints

| Endpoint | Method | Auth | Purpose | |---|---|---|---| | /api/v1/acknowledgements/monitoring | POST | yes | monitoring acknowledgment | | /api/v1/acknowledgements/role | POST | yes | role acceptance | | /api/v1/pairing/authorize-integrator | POST | home_admin | complete integrator pairing |

2.4 Site Telemetry Endpoints

| Endpoint | Method | Auth | Purpose | |---|---|---|---| | /api/v1/site/config | GET | yes | site config summary and bridge/runtime metadata | | /api/v1/site/status | GET | yes | operational status payload and harvested telemetry | | /api/v1/site/discovery | GET | yes | resolved harvest list and discovery diagnostics | | /api/v1/site/host-runtime | GET | yes | host runtime summary/detailed data |

/api/v1/site/host-runtime supports detail selection using:

query param detail=1|true|full|detailed|debug

2.5 Tools Endpoints

| Endpoint | Method | Auth | Purpose | |---|---|---|---| | /api/v1/tools/terminal/open | POST | tools role-gated | open terminal session | | /api/v1/tools/terminal/run | POST | tools role-gated | run allowed command in terminal session | | /api/v1/tools/terminal/close | POST | tools role-gated | close terminal session | | /api/v1/tools/host/reboot | POST | tools role-gated | guarded host reboot request | | /api/v1/tools/doorbell/status | GET | tools role-gated | doorbell reference/status metadata | | /api/v1/tools/doorbell/upload | POST | tools role-gated | upload custom doorbell WAV | | /api/v1/tools/doorbell/apply-sample | POST | tools role-gated | apply built-in sample | | /api/v1/tools/doorbell/sample-audio | GET | tools role-gated | stream built-in sample audio |

2.6 Admin Endpoints

| Endpoint | Method | Auth | Purpose | |---|---|---|---| | /api/v1/admin/users | GET/POST/PATCH/DELETE | user-mgmt role-gated | user lifecycle operations | | /api/v1/admin/home-admin-activation | POST | integrator | create home admin activation | | /api/v1/admin/home-admin-activation/resend | POST | integrator | resend activation | | /api/v1/admin/home-admin-activation/cancel | POST | integrator | cancel pending activation | | /api/v1/admin/monitoring | GET/POST | monitoring-manage role-gated | monitoring profile read/update | | /api/v1/admin/catalog | GET | monitoring-manage role-gated | services/devices/states/action catalog | | /api/v1/admin/audit | GET | integrator/home_admin | privileged audit access |

2.7 Homeowner Access-Control Endpoints

| Endpoint | Method | Auth | Purpose | |---|---|---|---| | /api/v1/home/revoke-integrator | POST | home_admin | permanent integrator revoke | | /api/v1/home/integrator-access | GET/POST | home_admin | temporary integrator enable/disable |

2.8 Audit Endpoint

| Endpoint | Method | Auth | Purpose | |---|---|---|---| | /api/v1/audit | GET | yes | role-filtered access/audit event stream |

3. Session and Authorization Semantics

3.1 Session Issuance

token
role
username
expires_in_seconds
gate flags such as:

- requires_password_change - requires_role_acknowledgement - requires_monitoring_acknowledgement - requires_integrator_authorization

3.2 Session Lifetime

Session expiry target: 28,800 seconds
Expired sessions are removed server-side

3.3 Common Authorization Outcomes

401 unauthorized for missing/invalid token
403 forbidden for role/action disallow
403 role_acknowledgement_required
403 monitoring_acknowledgement_required
403 password_change_required
403 integrator_access_temporarily_disabled (login path)

4. Initialization Mode Behavior

When pairing is not complete, site endpoints intentionally return constrained bootstrap payloads instead of full telemetry:

initialization_mode: true
pairing_state
limited bridge metadata

This supports guided setup UX while preventing ambiguous data exposure.

5. Request and Response Examples

Request:


{

  "username": "installer",

  "password": "SentinelLocal!234"

}

Response (example, abridged):


{

  "token": "abcdef...",

  "role": "integrator",

  "expires_in_seconds": 28790,

  "requires_password_change": false,

  "requires_monitoring_acknowledgement": false,

  "pairing_state": {

    "pairing_complete": true

  }

}

5.2 Site Config

Response fields of note:

bridge_version
bridge_pid
bridge_pid_file
transport_scheme
tls_enabled
tls_fingerprint
active_config_filename
harvest_mode
harvest_state_count
resolved_harvest_state_count
host_runtime
access

5.3 Homeowner Temporary Integrator Access

Disable integrator:


{

  "enabled": false

}

Enable integrator:


{

  "enabled": true

}

GET response includes:

enabled
temporarily_disabled
disabled_at
disabled_by

5.4 Admin User Create with Temporary Password

Request:


{

  "username": "new_home_user",

  "role": "home_user",

  "temporary_password": true,

  "email": "user@example.com"

}

Response may include:

created
temporary_password
requires_password_change
delivery_method
activation_delivery

6. Tools API Guardrails

6.1 Terminal

Terminal execution enforces:

authenticated role-gated session
session identity match on run/close
command allow checks
timeout controls
audit logging of command and exit status

6.2 Reboot

Reboot requests require:

warning_acknowledged = true
second_confirmation = true
non-empty sudo_password

6.3 Doorbell Audio

Upload/apply flow includes:

file-size cap (5 MB)
WAV compatibility checks against active reference audio
reference update backups
reload attempt with reboot recommendation when necessary

7. Audit and Compliance Data

Audit endpoints return:

retention_days
events (role-filtered)

Retention baseline:

90 days

Admin and homeowner critical actions emit explicit event types, including:

auth success/failure
role/monitoring acknowledgments
pairing authorization
user lifecycle changes
monitoring profile changes
integrator revoke/temporary disable events
terminal/reboot/doorbell tool actions

8. Operational Curl Reference

Root:


curl -k https://<HOST_IP>:42042/

Health:


curl -k https://<HOST_IP>:42042/health


curl -k -X POST https://<HOST_IP>:42042/api/v1/auth/login \

  -H "Content-Type: application/json" \

  -d '{"username":"installer","password":"<PASSWORD>"}'

Site config:


curl -k https://<HOST_IP>:42042/api/v1/site/config \

  -H "Authorization: Bearer <TOKEN>"

9. API Change Notes for v4.3 Beta

Compared with earlier branches, v4.3 beta emphasizes:

stronger pairing/governance payloads in session responses
PID and bridge runtime identity fields in site and health responses
homeowner temporary integrator access control endpoint
temporary password onboarding path in user creation flow
richer host/runtime and discovery diagnostics for app parsing

10. Implementation Notes for App Team

Trust /api/v1/site/config for bridge version and active config filename.
Handle initialization payloads distinctly from paired payloads.
Honor gate flags before presenting privileged actions.
Treat home/integrator-access as official endpoint even if root index does

not list it.

Surface endpoint errors directly with raw error value for faster support

triage.

Master Whitepaper Security Whitepaper Deployment Runbook All Downloads Back to Sentinel Pro

Sentinel Savant Rubi Bridge

Sentinel Savant Rubi Bridge

Protocol and API Specification (v4.3 Beta / v4.3b1-pro)

1. Transport and Protocol Baseline

1.1 Transport

1.2 Content Model

1.3 Authentication Header

1.4 Error Envelope (Typical)

2. Endpoint Inventory

2.1 Public/Bootstrap Endpoints

2.2 Authentication and Session Endpoints

2.3 Governance and Pairing Endpoints

2.4 Site Telemetry Endpoints

2.5 Tools Endpoints

2.6 Admin Endpoints

2.7 Homeowner Access-Control Endpoints

2.8 Audit Endpoint

3. Session and Authorization Semantics

3.1 Session Issuance

3.2 Session Lifetime

3.3 Common Authorization Outcomes

4. Initialization Mode Behavior

5. Request and Response Examples

5.1 Login

5.2 Site Config

5.3 Homeowner Temporary Integrator Access

5.4 Admin User Create with Temporary Password

6. Tools API Guardrails

6.1 Terminal

6.2 Reboot

6.3 Doorbell Audio

7. Audit and Compliance Data

8. Operational Curl Reference

9. API Change Notes for v4.3 Beta

10. Implementation Notes for App Team