REST API Reference¶

Section: Reference | Article 52
Audience: System Administrators, Developers
Last Updated: 2026-04-07

Overview¶

The RP-PAM REST API is served on port 7101 (default) and uses JSON for request and response bodies. All endpoints except /system/health/ping and /api/v1/auth/login require a valid JWT bearer token in the Authorization header.

Base URL¶

https://rppam.corp.local:7101

Authentication Header¶

Authorization: Bearer <jwt-token>

Common Response Codes¶

Code	Meaning
200	Success
201	Created
204	No Content (success, no body)
400	Bad Request (validation error)
401	Unauthorized (missing or invalid token)
403	Forbidden (insufficient permissions or license)
404	Not Found
409	Conflict (duplicate resource)
500	Internal Server Error

Authentication¶

Method	Path	Auth	Description
POST	`/api/v1/auth/login`	No	Authenticate with username and password; returns JWT
POST	`/api/v1/auth/mfa/challenge`	Yes	Submit MFA/TOTP code to complete authentication
POST	`/api/v1/auth/refresh`	Yes	Refresh an expiring JWT
POST	`/api/v1/auth/logout`	Yes	Invalidate the current token

Users¶

Method	Path	Auth	Description
GET	`/api/v1/users`	Yes	List all users (paginated)
GET	`/api/v1/users/{userId}`	Yes	Get user details
POST	`/api/v1/users`	Yes	Create a new user
PUT	`/api/v1/users/{userId}`	Yes	Update user details
DELETE	`/api/v1/users/{userId}`	Yes	Delete (soft-delete) a user
GET	`/api/v1/users/{userId}/roles`	Yes	List roles assigned to a user
PUT	`/api/v1/users/{userId}/roles`	Yes	Update roles for a user
POST	`/api/v1/users/{userId}/password/reset`	Yes	Initiate password reset
GET	`/api/v1/users/{userId}/grants`	Yes	List grants for a user

Resources¶

Method	Path	Auth	Description
GET	`/api/v1/resources`	Yes	List all managed resources (paginated)
GET	`/api/v1/resources/{resourceId}`	Yes	Get resource details
POST	`/api/v1/resources`	Yes	Register a new resource
PUT	`/api/v1/resources/{resourceId}`	Yes	Update resource details
DELETE	`/api/v1/resources/{resourceId}`	Yes	Remove a resource
GET	`/api/v1/resources/{resourceId}/grants`	Yes	List active grants for a resource

Vault¶

Method	Path	Auth	Description
GET	`/api/v1/vault/entries`	Yes	List vault entries (metadata only)
GET	`/api/v1/vault/entries/{entryId}`	Yes	Get vault entry details (metadata only)
POST	`/api/v1/vault/entries`	Yes	Create a new vault entry
PUT	`/api/v1/vault/entries/{entryId}`	Yes	Update a vault entry
DELETE	`/api/v1/vault/entries/{entryId}`	Yes	Delete a vault entry
POST	`/api/v1/vault/entries/{entryId}/retrieve`	Yes	Retrieve the decrypted secret value (audited)
POST	`/api/v1/vault/entries/{entryId}/rotate`	Yes	Rotate the secret value

Access Requests¶

Method	Path	Auth	Description
GET	`/api/v1/requests`	Yes	List access requests (filtered by user/role)
GET	`/api/v1/requests/{requestId}`	Yes	Get request details
POST	`/api/v1/requests`	Yes	Submit a new access request
POST	`/api/v1/requests/{requestId}/approve`	Yes	Approve a pending request
POST	`/api/v1/requests/{requestId}/deny`	Yes	Deny a pending request
POST	`/api/v1/requests/{requestId}/cancel`	Yes	Cancel a request (by the requester)

Grants¶

Method	Path	Auth	Description
GET	`/api/v1/grants`	Yes	List all grants (paginated, filterable)
GET	`/api/v1/grants/{grantId}`	Yes	Get grant details
POST	`/api/v1/grants/{grantId}/revoke`	Yes	Revoke an active grant
GET	`/api/v1/grants/{grantId}/credentials`	Yes	Retrieve grant credentials (one-time, audited)

Modules¶

Method	Path	Auth	Description
GET	`/api/v1/modules`	Yes	List all registered modules
GET	`/api/v1/modules/{moduleId}`	Yes	Get module details and status
POST	`/api/v1/modules`	Yes	Register a new module
PUT	`/api/v1/modules/{moduleId}`	Yes	Update module configuration
PATCH	`/api/v1/modules/{moduleId}`	Yes	Partial update (e.g., enable/disable)
DELETE	`/api/v1/modules/{moduleId}`	Yes	Remove a module
POST	`/api/v1/modules/{moduleId}/test`	Yes	Test module connectivity

Audit¶

Method	Path	Auth	Description
GET	`/api/v1/audit/events`	Yes	Query audit events (paginated, filterable by date, user, action)
GET	`/api/v1/audit/events/{eventId}`	Yes	Get audit event details
GET	`/api/v1/audit/events/export`	Yes	Export audit events as CSV or JSON for a date range
GET	`/api/v1/audit/summary`	Yes	Get audit summary statistics

Compliance¶

Method	Path	Auth	Description
POST	`/api/v1/compliance/reports`	Yes	Generate a compliance report package
GET	`/api/v1/compliance/reports`	Yes	List previously generated reports
GET	`/api/v1/compliance/reports/{reportId}/download`	Yes	Download a compliance report ZIP
GET	`/api/v1/compliance/attestation`	Yes	Get current control attestation (signed JSON)
GET	`/api/v1/compliance/schedules`	Yes	List scheduled compliance reports
POST	`/api/v1/compliance/schedules`	Yes	Create a compliance report schedule
DELETE	`/api/v1/compliance/schedules/{scheduleId}`	Yes	Delete a compliance report schedule

AI Assistant¶

Method	Path	Auth	Description
POST	`/api/v1/ai/chat`	Yes	Send a message to the AI assistant
GET	`/api/v1/ai/chat/history`	Yes	Get chat history for the current user
GET	`/api/v1/ai/status`	Yes	Get AI provider status and configuration
POST	`/api/v1/ai/suggest`	Yes	Get AI-generated suggestions for a request or workflow

MSP (Multi-Tenancy)¶

Method	Path	Auth	Description
GET	`/api/v1/msp/tenants`	Yes	List all tenants
GET	`/api/v1/msp/tenants/{tenantId}`	Yes	Get tenant details
POST	`/api/v1/msp/tenants`	Yes	Provision a new tenant
POST	`/api/v1/msp/tenants/{tenantId}/suspend`	Yes	Suspend a tenant
POST	`/api/v1/msp/tenants/{tenantId}/reinstate`	Yes	Reinstate a suspended tenant
POST	`/api/v1/msp/tenants/{tenantId}/deprovision`	Yes	Deprovision a tenant (30-day retention)
GET	`/api/v1/msp/tenants/{tenantId}/health`	Yes	Get tenant health status
GET	`/api/v1/msp/tenants/{tenantId}/billing-events`	Yes	Get billing events for a tenant
GET	`/api/v1/msp/billing-events`	Yes	Get billing events across all tenants

Admin¶

Method	Path	Auth	Description
GET	`/api/v1/admin/license`	Yes	Get current license details
PUT	`/api/v1/admin/license`	Yes	Apply a new license key
GET	`/api/v1/admin/cluster/status`	Yes	Get HA cluster status
POST	`/api/v1/admin/cluster/promote`	Yes	Force-promote a node to leader
POST	`/api/v1/admin/cluster/demote`	Yes	Demote a node to standby
GET	`/api/v1/admin/encryption/status`	Yes	Get encryption key hierarchy status
POST	`/api/v1/admin/encryption/repair`	Yes	Repair missing CEKs
POST	`/api/v1/admin/encryption/rotate-kek`	Yes	Rotate the KEK
GET	`/api/v1/admin/siem/status`	Yes	Get SIEM integration status
POST	`/api/v1/admin/siem/test`	Yes	Send a test event to SIEM targets
GET	`/api/v1/admin/updates/status`	Yes	Get update/patch history
GET	`/api/v1/admin/config`	Yes	Get current runtime configuration (redacted)
PUT	`/api/v1/admin/config`	Yes	Update runtime configuration

Break-Glass Emergency Access¶

Method	Path	Auth	Description
POST	`/api/v1/breakglass/activate`	Yes	Activate break-glass emergency access
POST	`/api/v1/breakglass/deactivate`	Yes	Deactivate break-glass mode
GET	`/api/v1/breakglass/status`	Yes	Get current break-glass status
GET	`/api/v1/breakglass/audit`	Yes	Get break-glass audit trail

System Health (No Authentication Required)¶

Method	Path	Auth	Description
GET	`/system/health/ping`	No	Basic health check (returns version, status)
GET	`/system/health/detail`	Yes	Detailed health check (database, vault, scheduler)
GET	`/system/health/ready`	No	Readiness probe (for Kubernetes/load balancers)
GET	`/system/health/live`	No	Liveness probe (for Kubernetes)

Pagination¶

List endpoints support pagination via query parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-based)
`pageSize`	integer	25	Items per page (max 100)
`sortBy`	string	varies	Sort field name
`sortOrder`	string	`asc`	`asc` or `desc`

Example:

GET /api/v1/users?page=2&pageSize=50&sortBy=displayName&sortOrder=asc

Paginated responses include:

{
  "items": [...],
  "page": 2,
  "pageSize": 50,
  "totalItems": 247,
  "totalPages": 5
}

Filtering¶

Many list endpoints support filtering via query parameters. Common filters:

Parameter	Example	Description
`status`	`?status=active`	Filter by status
`from` / `to`	`?from=2026-01-01&to=2026-03-31`	Date range filter
`userId`	`?userId=abc123`	Filter by user
`resourceId`	`?resourceId=res456`	Filter by resource
`moduleType`	`?moduleType=ssh`	Filter by module type
`search`	`?search=john`	Free-text search

Rate Limiting¶

The API enforces rate limits per authenticated user:

Tier	Limit	Window
Standard endpoints	100 requests	Per minute
Auth endpoints	10 requests	Per minute
Report generation	5 requests	Per hour

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header.

Next Steps¶

Configuration Reference — Full configuration file reference
Support Contact — API support and questions