> For the complete documentation index, see [llms.txt](https://docs.scepman.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scepman.com/certificate-management/management-rest-api.md).

# Management REST API

{% hint style="warning" %}
SCEPman Enterprise Edition only

Applicable to version 3.1 and above
{% endhint %}

The Management API provides administrative access to issued certificates in SCEPman. It is intended for management and operational workflows such as locating certificates and revoking them when needed.

These endpoints are available under `/api/manage` and require an authenticated user with the **Manage.All** role in SCEPman-api.

{% hint style="info" %}
If you update from an earlier SCEPman version, you might not yet have the Manage.All role. Run `Complete-SCEPmanInstallation` again in a cloud shell to automatically add it to your SCEPman-api application.
{% endhint %}

## Authentication

The API uses Entra authentication. The easiest way to authenticate is often the Microsoft Authentication Library (MSAL).

One way to get a bearer token for the Management API is with the Azure CLI. The required value for the \`--resource\` parameter is the Application ID URI of your SCEPman-api app registration (usually its Application ID prefixed with `api://`).

```bash
az account get-access-token --resource api://[APPLICATION-ID] --query accessToken --output tsv
```

For example:

```bash
TOKEN=$(az account get-access-token \
  --resource api://16b6a4d1-0a20-4b41-bf58-12783034cad3 \
  --query accessToken \
  --output tsv)
```

You can then use that token in the API calls:

```bash
curl -X GET "https://scepman.contoso.com/api/manage/search?searchText=ABC123&pageSize=10&certValidity=Any&certType=Any" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

## Search API

**`GET /api/manage/search`**

Searches issued certificates and returns a paginated result set.

### Search parameters

**`searchText`**

Free-text search term used to find matching certificates. This is typically used for substring-based lookups, for example matching requester or other searchable certificate metadata.

**`pageSize`**

Maximum number of certificates returned in a single response page.

* Default: 50

**`continuationToken`**

Optional pagination token used to request the next page of results.\
Pass back the `continuationToken` returned by a previous search response to continue fetching more certificates.

**`certValidity`**

Filters certificates by validity state.

* Default: `Any`

Valid values are `Any`, `Active`, `Expired`, `Revoked`.

**`certType`**

Filters certificates by certificate type.

* Default: `Any`

This can be used to restrict the result set to specific certificate categories. Valid values are `Static`, `DC`, `User`, `Device`, and `Any`.

**`Sources`**

Filters certificates by the endpoint through which they have been issued. You can specify this filter multiple times, once per source.

* Default: No restriction

Valid values are shown in the table below, you must specify the source using their integer values:

| Source            | Value                                   |
| ----------------- | --------------------------------------- |
| CertificateMaster | 0                                       |
| Intune            | 1 or 9 (use both to ensure finding all) |
| Static            | 3                                       |
| StaticAAD         | 4                                       |
| Jamf              | 5                                       |
| DomainController  | 6                                       |
| API               | 7                                       |
| RadiusAPI         | 8                                       |
| Active Directory  | 10                                      |

### **Example**

```bash
curl -X GET "https://scepman.contoso.com/api/manage/search?searchText=507AEAC03CCEF83F106914418D9222E466A629C1&pageSize=10&certValidity=Any&certType=Any" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"
```

#### **Example response**

```json
{
  "items": [
    {
    "serialNumber":  "507AEAC03CCEF83F106914418D9222E466A629C1",
    "subject":  "CN=device01.contoso.local",
    "sans":  null,
    "upn":  null,
    "issuanceDate":  "2026-05-28T10:57:22Z",
    "expirationDate":  "2028-05-28T10:57:22Z",
    "revocationDate":  null,
    "revocationReason":  null,
    "revokedBy":  null,
    "requester":  "pkiAdmin@contoso.com",
    "source":  "CertificateMaster",
    "certificateType":  "Static"
    }
  ],
  "continuationToken": "...",
  "fullTextSearch": false
}
```

### **Response fields**

**`items`**

The certificates of the current page.

**`continuationToken`**

An opaque token for fetching the next page. It is `null` when the last page has been reached.

{% hint style="info" %}
Treat the continuation token as opaque and pass it back unchanged. Do not modify it, do not persist it across long periods, and do not reuse it with different search parameters — a token is only valid for the exact query that produced it.
{% endhint %}

**`fullTextSearch`**

Indicates which kind of text matching produced this result.

* `true` — `searchText` was matched **anywhere** within the searched fields (full-text search).
* `false` — `searchText` was only matched against the **beginning** of the searched fields (prefix search).

The field is also present when no `searchText` was given; it is `false` in that case.

{% hint style="info" %}
`fullTextSearch` is available from SCEPman 3.2. SCEPman 3.1 omits it and always performs a prefix search.
{% endhint %}

### Search Behaviour

#### **Full-text search vs. prefix search**

SCEPman chooses the search strategy automatically and the strategy selection may change with future version of SCEPman and especially based on the number of certificates in your environment.

* For `"fullTextSearch": true`, SCEPman uses a case-insensitive **substring** match over serial number, subject, SANs, UPN, requester, revoker and certificate type.
* For  `"fullTextSearch": false`, the search matches only at the **beginning** of a field. Matched fields are serial number, UPN, requester, revoker and subject. The subject search includes both the raw subject and the Common Name RDN, e.g. searching for `device01` would match a certificate with subject `CN=device01`.

{% hint style="warning" %}
Because API clients cannot control the specific strategy employed, you should not rely on a specific strategy being used and be able to handle both amounts of certificates.&#x20;
{% endhint %}

### Error response

#### **Invalid continuation token**

```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
```

```json
{
  "errorMessage": "The continuation token is invalid. Please repeat the search without a continuation token.",
  "errorCode": 4014
}
```

The error with errorCode 4014 happens when a continuation token cannot be interpreted. Repeat the search from the first page without a continuation token.

## **Revocation API**

**`PATCH /api/manage/revoke/{serialNumber}`**

Revokes a certificate identified by its serial number.

The request body contains:

* `revocationReason` - an integer for the reason of revocation. See the table below for possible values
* `revoker` *(optional)* - a free-text identifier for the person or system requesting revocation

{% hint style="info" %}
If specified, we recommend to use the UPN for the revoker field. If not specified, the logged on user's UPN will be used. Even if specified, the logged on user's UPN is still added in the form "{revoker} through API user ${logged on user}".

This value is used for auditing and in searches.
{% endhint %}

### **Example**

```bash
curl -X PATCH "https://scepman.contoso.com/api/manage/revoke/ABC123" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "revocationReason": 4,
    "revoker": "pkiAdmin@contoso.com"
  }'
```

#### **Successful response**

```http
HTTP/1.1 200 OK
```

#### **Certificate not found**

```http
HTTP/1.1 404 Not Found
Content-Type: application/json
```

```json
{
  "errorMessage": "Certificate not found.",
  "errorCode": 7012
}
```

#### **Already revoked**

```http
HTTP/1.1 409 Conflict
Content-Type: application/json
```

```json
{
  "errorMessage": "The certificate is already revoked.",
  "errorCode": 5013
}
```

### Supported revocation reasons

The API supports the revocation reasons specified in [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280#section-5.3.1):

| Value | Revocation Reason    |
| ----- | -------------------- |
| 0     | Unspecified          |
| 1     | KeyCompromise        |
| 2     | CACompromise         |
| 3     | AffiliationChanged   |
| 4     | Superseded           |
| 5     | CessationOfOperation |
| 6     | CertificateHold      |
| 8     | RemoveFromCrl        |
| 9     | PrivilegeWithdrawn   |
| 10    | AACompromise         |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.scepman.com/certificate-management/management-rest-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
