- Overview
- Reference Guide
- Setup & Architecture
- Release Notes
- Workflow
- API Reference
- Integration Guide
- Discovery Agent Setup Guide
Request and Response Conventions
The conventions on this page apply to all CertSecure Manager API endpoints unless an endpoint states otherwise.
Request Headers
| Header | Value | Description |
|---|---|---|
Authorization |
Bearer <token> |
API token of the caller. Required for all endpoints except the public endpoints. |
Content-Type |
application/json |
Required for requests that send a JSON body. |
Content-Type |
multipart/form-data |
Required for requests that send form fields or upload a file, such as discovery configurations and bulk CSV uploads. |
Accept |
application/json |
Optional. Most endpoints return JSON. |
Request Parameters
Endpoints receive their input in one of the following ways. The endpoint pages list the parameters and where each is located.
| Located In | Description |
|---|---|
| Path |
Part of the endpoint path, for example the vault name in
/azureKeyVault/{name}.
|
| Query |
Appended to the URL, for example
/inventory/count?ca=Example%20Issuing%20CA. URL-encode
values that contain spaces or special characters.
|
| Body (JSON) | A JSON object sent with POST, PUT, PATCH, or DELETE requests. |
| Body (form data) | Form fields or files sent as multipart/form-data. |
Identifying Certificates
Endpoints that act on a single certificate identify it in one of the following ways:
| Identifier | Description |
|---|---|
Enrollment ID (eid or EnrollmentID) |
The ID CertSecure Manager assigns to each certificate it enrolls or imports. |
Serial number and CA (serialNum and ca) |
The certificate serial number together with the name of the issuing CA. |
Task ID (taskID) |
The ID of the task created for an operation, used to download its results. |
CA and template names are the names shown in the CertSecure Manager portal. To list them, call GET /available_ca and GET /enrollment/templates.
Pagination
Endpoints that return long lists accept page with
count (or per_page) query parameters.
page selects the page to return, starting at 1, and
count sets the number of records per page. For example:
curl -X GET "https://<certsecure-backend-url>/inventory?page=1&count=50" \
-H "Authorization: Bearer <token>"Responses
Successful requests return JSON. Endpoints that export data return a file
instead, for example PEM or PFX certificates, ZIP archives, CSV text, or XLSX
workbooks. Some count endpoints return an object keyed by category, for example
{"active": 2835, "expired": 967}.
Error responses carry a short message in a JSON object. Depending on the
endpoint, the message is returned under Error, error,
or message:
{
"Error": "ca should be passed as a parameter"
}HTTP Status Codes
| Status Code | Description |
|---|---|
| 200 OK | The request succeeded. |
| 202 Accepted | The request was accepted and is still being processed, for example while discovery data is being synchronized. |
| 400 Bad Request | A required parameter is missing or a value is invalid. The response body describes the problem. |
| 401 Unauthorized | The token is missing, invalid, expired, or revoked. Refer to Authentication Errors. |
| 403 Forbidden | The token is valid, but its user does not have permission for the operation or the resource. |
| 404 Not Found | The endpoint or the requested resource does not exist. |
| 409 Conflict | The resource already exists, or the operation cannot run in the current state. |
| 500 Internal Server Error | The request could not be completed because of an error on the backend or in a connected system. |
| 502 Bad Gateway | A connected external system, such as Splunk, could not be reached or rejected the request. |
Trailing Slashes
Call endpoints exactly as they are written in this reference. In particular, the
/inventory, /enrollment, /reports, and
/tasks endpoints must be called without a trailing slash; with a
trailing slash, the request returns 404 Not Found.