Sentinel Privilege Manager — REST API Documentation

1. API Overview

The Sentinel Privilege Manager REST API provides programmatic access to platform resources and management operations.

Applications can use the API to retrieve users, manage endpoints, create privilege policies, and retrieve security activity.

What can you do with the API? The API enables authorized applications to integrate Sentinel Privilege Manager with internal applications, automation workflows, security platforms, and reporting systems.

1.1 API Characteristics

RESTful

Uses standard HTTP methods and resource-oriented endpoints.

JSON

Request and response payloads use JSON format.

HTTPS

API communication is performed over HTTPS.

Versioned

API endpoints are versioned to support controlled changes.

2. Authentication

API requests must be authenticated using a valid access token.

Security Requirement Treat API credentials as sensitive information. Do not expose access tokens in source code, public repositories, client-side applications, or logs.

2.1 Authorization Header

Include the access token in the Authorization header.

Authorization: Bearer <access_token>

2.2 Example Request

curl -X GET "https://api.spm.example.com/v1/users" \
-H "Authorization: Bearer <access_token>" \
-H "Accept: application/json"

3. Base URL

All API endpoints are relative to the following base URL.

https://api.spm.example.com/v1

3.1 Endpoint Structure

https://api.spm.example.com/v1/{resource}

For example, the Users endpoint is:

https://api.spm.example.com/v1/users

4. HTTP Headers

The following headers can be used when making API requests.

Header	Required	Description	Example
`Authorization`	Yes	Access token used to authenticate the request.	Bearer token
`Accept`	Recommended	Specifies the expected response format.	application/json
`Content-Type`	For requests with a body	Specifies the request payload format.	application/json

5. Response Format

Successful API requests return JSON responses.

5.1 Example Response

{
    "success": true,
    "data": {
        "id": "usr_10245",
        "username": "alex.smith",
        "email": "alex.smith@example.com",
        "status": "active",
        "role": "security-admin"
    }
}

5.2 Collection Response

{
    "success": true,
    "data": [
        {
            "id": "usr_10245",
            "username": "alex.smith",
            "status": "active"
        },
        {
            "id": "usr_10246",
            "username": "jordan.lee",
            "status": "active"
        }
    ]
}

6. HTTP Status Codes

Status Code	Meaning	Description
200	OK	Request completed successfully.
201	Created	Resource was created successfully.
400	Bad Request	Request contains invalid or missing information.
401	Unauthorized	Authentication credentials are missing or invalid.
403	Forbidden	Authenticated user does not have permission to perform the operation.
404	Not Found	Requested resource does not exist.
429	Too Many Requests	Request limit has been exceeded.
500	Internal Server Error	Unexpected server-side error.

7. User APIs

User APIs allow authorized applications to retrieve and manage user information.

GET /users

List Users

Retrieves a list of users available to the authenticated administrator.

Query Parameters

Parameter	Type	Required	Description
`page`	Integer	No	Page number to retrieve.
`limit`	Integer	No	Number of records returned per page.
`status`	String	No	Filters users by status.

Example Request

GET /v1/users?page=1&limit=20&status=active

Example Response

{
    "success": true,
    "data": [
        {
            "id": "usr_10245",
            "username": "alex.smith",
            "email": "alex.smith@example.com",
            "status": "active"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 20,
        "total": 1
    }
}

GET /users/{userId}

Get User

Retrieves details for a specific user.

Path Parameters

Parameter	Type	Required	Description
`userId`	String	Yes	Unique identifier of the user.

Example Request

GET /v1/users/usr_10245

Example Response

{
    "success": true,
    "data": {
        "id": "usr_10245",
        "username": "alex.smith",
        "email": "alex.smith@example.com",
        "role": "security-admin",
        "status": "active"
    }
}

8. Endpoint APIs

Endpoint APIs provide access to managed endpoint information.

GET /endpoints

List Endpoints

Retrieves managed endpoints associated with the authenticated account.

Example Request

GET /v1/endpoints?page=1&limit=20

Example Response

{
    "success": true,
    "data": [
        {
            "id": "ep_50123",
            "name": "FIN-LAPTOP-023",
            "os": "Windows 11",
            "agentVersion": "3.2.1",
            "status": "online"
        }
    ]
}

GET /endpoints/{endpointId}

Get Endpoint Details

Retrieves detailed information for a specific managed endpoint.

Example Request

GET /v1/endpoints/ep_50123

Example Response

{
    "success": true,
    "data": {
        "id": "ep_50123",
        "name": "FIN-LAPTOP-023",
        "os": "Windows 11",
        "ipAddress": "192.0.2.25",
        "agentVersion": "3.2.1",
        "status": "online",
        "lastCheckIn": "2026-09-17T10:30:00Z"
    }
}

9. Policy APIs

Policy APIs allow authorized applications to retrieve and create privilege policies.

GET /policies

List Policies

Retrieves privilege policies configured in Sentinel Privilege Manager.

Example Request

GET /v1/policies

Example Response

{
    "success": true,
    "data": [
        {
            "id": "pol_20001",
            "name": "Approved Developer Tools",
            "status": "active",
            "targetType": "user-group"
        }
    ]
}

POST /policies

Create Policy

Creates a new privilege policy.

Request Body

{
    "name": "Approved Developer Tools",
    "description": "Controlled elevation for approved tools",
    "targetType": "user-group",
    "targetId": "grp_30001",
    "status": "active"
}

Example Request

POST /v1/policies

Content-Type: application/json

{
    "name": "Approved Developer Tools",
    "description": "Controlled elevation for approved tools",
    "targetType": "user-group",
    "targetId": "grp_30001",
    "status": "active"
}

Example Response

{
    "success": true,
    "data": {
        "id": "pol_20002",
        "name": "Approved Developer Tools",
        "status": "active"
    }
}

10. Activity APIs

Activity APIs provide access to privilege-related events recorded by Sentinel Privilege Manager.

GET /activity

List Activity Events

Retrieves activity events based on the supplied filters.

Query Parameters

Parameter	Type	Required	Description
`endpointId`	String	No	Filters events by endpoint.
`eventType`	String	No	Filters events by event type.
`from`	DateTime	No	Start date and time for the activity range.
`to`	DateTime	No	End date and time for the activity range.

Example Request

GET /v1/activity?endpointId=ep_50123&eventType=elevation

Example Response

{
    "success": true,
    "data": [
        {
            "id": "evt_80001",
            "eventType": "elevation",
            "endpointId": "ep_50123",
            "application": "DeveloperTool.exe",
            "result": "allowed",
            "timestamp": "2026-09-17T10:30:00Z"
        }
    ]
}

11. Pagination

Collection endpoints support pagination to control the number of records returned in a single response.

11.1 Pagination Parameters

Parameter	Description	Example
`page`	Page number.	1
`limit`	Number of records returned per page.	20

11.2 Example

GET /v1/users?page=2&limit=20

The response includes pagination metadata to help the client determine the total number of available records.

"pagination": {
    "page": 2,
    "limit": 20,
    "total": 75
}

12. Error Handling

When an API request cannot be completed, SPM returns an HTTP error status and a JSON response describing the issue.

12.1 Error Response

{
    "success": false,
    "error": {
        "code": "INVALID_REQUEST",
        "message": "The policy name is required.",
        "details": []
    }
}

12.2 Common Error Codes

Error Code	Description	HTTP Status
`INVALID_REQUEST`	One or more request fields are invalid.	400
`AUTHENTICATION_FAILED`	Authentication credentials are missing or invalid.	401
`ACCESS_DENIED`	The authenticated user does not have permission.	403
`RESOURCE_NOT_FOUND`	The requested resource does not exist.	404
`RATE_LIMIT_EXCEEDED`	The API request limit has been exceeded.	429
`INTERNAL_ERROR`	An unexpected server-side error occurred.	500

13. Rate Limits

Rate limits help maintain API availability and prevent excessive requests.

Portfolio Example The limits shown in this sample are illustrative values for demonstrating API documentation structure.

API Category	Example Limit	Window
Read Operations	100 requests	Per minute
Write Operations	30 requests	Per minute
Reporting APIs	20 requests	Per minute

If the rate limit is exceeded, the API returns 429 Too Many Requests.

14. Integration Workflow

A typical application integration with the SPM REST API follows the workflow below.

1. Authenticate

Obtain a valid access token using the organization's approved authentication flow.

2. Send Request

Send an HTTPS request with the required headers and parameters.

3. Process Response

Parse the JSON response and handle the returned status code.

4. Handle Errors

Process API errors and implement appropriate retry or remediation logic.

14.1 Example Integration Flow

Client Application
        |
        |  Authenticate
        v
Access Token
        |
        |  HTTPS API Request
        v
Sentinel Privilege Manager API
        |
        |  JSON Response
        v
Client Application
        |
        |  Process Result
        v
Application Workflow

Integration Complete Once authentication, request processing, response handling, and error handling have been implemented, the client application can interact with the supported SPM API resources.

Document Information

Document Type	REST API Documentation
Product	Sentinel Privilege Manager
API Version	v1
Format	JSON
Audience	Developers, Integrators, and Security Engineers
Status	Portfolio Sample
Author	Anshula Raina

Portfolio Disclaimer: Sentinel Privilege Manager is a fictional product created for demonstration purposes. API endpoints, authentication flows, request parameters, response structures, URLs, limits, and example values in this document are illustrative and are not intended for production use.