Skip to content

REST_API.md

Latest commit

 

History

History
195 lines (163 loc) · 9.82 KB

REST_API.md

File metadata and controls

195 lines (163 loc) · 9.82 KB
Raw

Linux Patch Manager REST API Reference

Base URL: /api/v1/ Content-Type: application/json Security: JWT Bearer Token (except Public Endpoints)

1. Authentication & Session

Method Endpoint Description
POST /auth/login Authenticate user
POST /auth/logout Invalidate current session
POST /auth/refresh Refresh JWT token
GET /auth/mfa/setup Generate MFA setup QR/code
POST /auth/mfa/verify Verify MFA code
DELETE /auth/mfa Disable MFA for user

1b. SSO (Single Sign-On)

No authentication required. These endpoints implement the OIDC Authorization Code + PKCE flow. See tasks/sso-token-handoff-spec.md for the full design.

Method Endpoint Description
GET /auth/sso/login Initiate OIDC login: redirects browser to the configured IdP's authorization URL
GET /auth/sso/callback OIDC redirect URI: handles the IdP response, issues a single-use 60s handoff_code, stores the JWT access/refresh tokens in memory, and 302-redirects to the SPA with ?handoff=<code> in the URL (no tokens in the URL — see issue #4)
GET /auth/sso/config Returns minimal SSO configuration for the login page (enabled, display_name, auth_url). No secrets exposed
POST /auth/sso/handoff (new in issue #4) Exchange a single-use handoff_code for the JWT access/refresh tokens. The SPA calls this from SsoCallbackPage after the OIDC callback redirect. Returns { access_token, refresh_token, token_type, expires_in, user }. The code is single-use, 60s TTL, and atomically removed on exchange (concurrent attempts: exactly one wins). 400 invalid_handoff on unknown/expired/already-consumed codes

2. Public Endpoints (Self-Enrollment)

No authentication required.

Method Endpoint Description
POST /enroll Submit host enrollment request
GET /enroll/status/{token} Poll enrollment approval status & retrieve PKI

3. Administration (Enrollment Queue)

Requires Admin role.

Method Endpoint Description
GET /admin/enrollments List pending enrollment requests
POST /admin/enrollments/{id}/approve Approve request, generate PKI, migrate to hosts
DELETE /admin/enrollments/{id}/deny Deny and purge enrollment request

4. Host Management

Method Endpoint Description
GET /hosts List managed hosts
POST /hosts Register host manually
GET /hosts/{id} Get host details
DELETE /hosts/{id} Remove host
POST /hosts/{id}/refresh Trigger on-demand data refresh
DELETE /hosts/{id}/groups/{group_id} Remove host from group

5. Certificate Management

Method Endpoint Description
GET /ca/root.crt Download Root CA certificate
GET /certificates List issued certificates (grouped by status/host)
DELETE /certificates/{cert_id} Revoke certificate
POST /certificates/{cert_id}/renew Renew certificate
POST /hosts/{host_id}/certificates Issue client certificate for host
POST /hosts/{host_id}/certificates/reissue Reissue host certificates
GET /hosts/{host_id}/client.crt Download client certificate

6. Discovery & Network Scanning

Method Endpoint Description
POST /discovery/cidr Start CIDR network scan
GET /discovery/{scan_id} Get scan results
POST /discovery/{id}/register Register discovered host

7. Jobs & Patch Deployment

Method Endpoint Description
GET /jobs List patch jobs (includes host_names per job)
POST /jobs Create new patch job
GET /jobs/{id} Get job status/details
POST /jobs/{id}/cancel Cancel running job
POST /jobs/{id}/rollback Rollback completed job

GET /jobs Response Fields

Each job summary object includes:

  • host_names: Array of display names for hosts targeted by this job. Falls back to fqdn when display_name is empty. Single-host jobs show one name; multi-host jobs show all names sorted alphabetically.

8. Maintenance Windows

Scoped to host.

Method Endpoint Description
GET /hosts/{host_id}/maintenance-windows List windows for host
POST /hosts/{host_id}/maintenance-windows Create window
PUT /hosts/{host_id}/maintenance-windows/{win_id} Update window
DELETE /hosts/{host_id}/maintenance-windows/{win_id} Delete window

9. Health Checks

Method Endpoint Description
GET /health-checks List health checks
POST /health-checks Create health check
POST /health-checks/{check_id}/test Run manual health check

10. Users & Groups

Method Endpoint Description
GET /users List users
POST /users Create user
GET /users/{id} Get user details
PUT /users/{id} Update user
DELETE /users/{id} Delete user
PUT /users/{id}/password Admin reset password
POST /users/{id}/revoke Revoke all user sessions
DELETE /users/{id}/mfa Admin disable MFA
GET /users/me Get current authenticated user
PUT /users/me/password Change own password
GET /groups List groups
POST /groups Create group

11. Settings & Configuration

Method Endpoint Description
GET /settings Get system settings
PUT /settings Update system settings (Admin only — Operators receive 403 forbidden_role)
POST /settings/smtp/test Test SMTP configuration
POST /settings/sso/discover Discover OIDC provider config (Admin only — Operators receive 403 forbidden_role)
POST /settings/sso/test Test SSO connection (Admin only — Operators receive 403 forbidden_role)
POST /settings/azure-sso/test Test Azure SSO compatibility
POST /settings/audit-integrity Verify audit log integrity

Note (issue #6): As of May 2026, sensitive fields (oidc.client_secret, smtp.password) are encrypted at rest in the database (AES-256-GCM). The MASKED placeholder behavior in API responses is preserved — clients never see plaintext secrets in GET responses. See docs/runbooks/key-management.md for key management procedures.

12. Single Sign-On (SSO)

Method Endpoint Description
GET /sso/config Get SSO configuration status
GET /sso/login Initiate SSO login flow
GET /sso/callback Handle SSO provider callback

13. Reports & Status

Method Endpoint Description
GET /status/fleet Get fleet-wide status summary
GET /reports/compliance Generate compliance report
GET /reports/patch-history Generate patch history report
GET /reports/vulnerability Generate vulnerability exposure report
GET /reports/audit Generate audit trail report

CRL Status Fields

Host list and detail responses include CRL (Certificate Revocation List) status fields:

Field Type Description
crl_status string? CRL status: valid, expired, missing, invalid, or null (older agents)
crl_age_seconds integer? Seconds since the agent's CRL was last refreshed
crl_next_update datetime? When the agent's CRL expires (ISO-8601)

Fleet status response includes CRL counts:

Field Type Description
crl_valid integer Hosts with CRL status valid
crl_expired integer Hosts with CRL status expired
crl_missing integer Hosts with CRL status missing
crl_invalid integer Hosts with CRL status invalid (security event)
crl_not_reporting integer Hosts not reporting CRL status (older agents)

CRL Audit Events

The health poller logs the following system-initiated audit events when a host's CRL status changes:

Audit Action Trigger Details Fields
crl_status_changed Any CRL status transition host_id, old_crl_status, new_crl_status, crl_age_seconds
crl_stale_detected CRL status becomes expired host_id, old_crl_status, new_crl_status, crl_age_seconds
crl_invalid CRL status becomes invalid host_id, old_crl_status, new_crl_status, crl_age_seconds

All CRL audit events use target_type = "host" and target_id = <host_id>. Actor fields (actor_user_id, actor_username) are null because these are system-initiated events.

CRL Health Aggregation Rules

The health poller applies the following rules to determine a host's effective health status based on CRL state:

CRL Status Condition Effective Health Status
invalid Always unreachable (security event)
expired If natural status is healthy degraded
missing Registered > 24h ago AND natural status is healthy degraded
missing Registered ≤ 24h ago Natural status (new agent enrollment)
valid Any Natural status (no override)
null Any Natural status (older agent, not reporting CRL)

When CRL status transitions from invalid/expired/missing back to valid, the next health poll cycle restores the host to its natural health status based on the agent's health response.

14. Real-Time Updates (WebSocket)

Method Endpoint Description
POST /ws/ticket Request WebSocket auth ticket
GET /ws/jobs Upgrade to WebSocket for job streaming