> 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/de/zertifikatsverwaltung/management-rest-api.md).

# Verwaltungs-REST-API

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

Gilt ab Version 3.1
{% endhint %}

Die Verwaltungs-API bietet administrativen Zugriff auf in SCEPman ausgestellte Zertifikate. Sie ist für Verwaltungs- und Betriebsabläufe vorgesehen, beispielsweise zum Auffinden von Zertifikaten und zu deren Sperrung bei Bedarf.

Diese Endpunkte sind verfügbar unter `/api/manage` und erfordern einen authentifizierten Benutzer mit der Rolle **Manage.All** in SCEPman-api.

{% hint style="info" %}
Wenn Sie von einer früheren SCEPman-Version aktualisieren, ist die Rolle Manage.All möglicherweise noch nicht vorhanden. Führen Sie `Complete-SCEPmanInstallation` erneut in einer Cloud Shell aus, um sie automatisch Ihrer SCEPman-api-Anwendungsregistrierung hinzuzufügen.
{% endhint %}

## Authentifizierung

Die API verwendet Entra-Authentifizierung. Am einfachsten erfolgt die Authentifizierung häufig mit der Microsoft Authentication Library (MSAL).

Eine Möglichkeit, ein Bearer-Token für die Verwaltungs-API abzurufen, ist die Azure CLI. Der erforderliche Wert für den Parameter \`--resource\` ist der Anwendungs-ID-URI Ihrer SCEPman-api-App-Registrierung (in der Regel die Anwendungs-ID mit vorangestelltem `api://`).

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

Beispiel:

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

Anschließend können Sie dieses Token in den API-Aufrufen verwenden:

```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"
```

## Such-API

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

Durchsucht ausgestellte Zertifikate und gibt eine paginierte Ergebnismenge zurück.

### Suchparameter

**`searchText`**

Freitext-Suchbegriff zum Auffinden passender Zertifikate. Dieser wird typischerweise für Teilzeichenfolgen-Suchen verwendet, zum Beispiel zum Abgleichen des Antragstellers oder anderer durchsuchbarer Zertifikatsmetadaten.

**`pageSize`**

Maximale Anzahl der Zertifikate, die auf einer einzelnen Ergebnisseite zurückgegeben werden.

* Standardwert: 50

**`continuationToken`**

Optionales Paginierungstoken zum Anfordern der nächsten Ergebnisseite.\
Geben Sie das `continuationToken` zurück, das von einer vorherigen Suchantwort geliefert wurde, um weitere Zertifikate abzurufen.

**`certValidity`**

Filtert Zertifikate nach Gültigkeitsstatus.

* Standardwert: `Any`

Gültige Werte sind `Any`, `Active`, `Expired`, `Revoked`.

**`certType`**

Filtert Zertifikate nach Zertifikatstyp.

* Standardwert: `Any`

Damit lässt sich die Ergebnismenge auf bestimmte Zertifikatskategorien beschränken. Gültige Werte sind `Static`, `DC`, `User`, `Device` und `Any`.

**`Sources`**

Filtert Zertifikate nach dem Endpunkt, über den sie ausgestellt wurden. Sie können diesen Filter mehrfach angeben, jeweils einmal pro Quelle.

* Standard: Keine Einschränkung

Die gültigen Werte sind in der folgenden Tabelle aufgeführt. Die Quelle muss über ihren ganzzahligen Wert angegeben werden:

| Quelle            | Wert                                              |
| ----------------- | ------------------------------------------------- |
| CertificateMaster | 0                                                 |
| Intune            | 1 oder 9 (verwenden Sie beide, um alle zu finden) |
| Static            | 3                                                 |
| StaticAAD         | 4                                                 |
| Jamf              | 5                                                 |
| DomainController  | 6                                                 |
| API               | 7                                                 |
| RadiusAPI         | 8                                                 |
| Active Directory  | 10                                                |

### **Beispiel**

```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"
```

#### **Beispielantwort**

```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
}
```

### **Antwortfelder**

**`items`**

Die Zertifikate der aktuellen Seite.

**`continuationToken`**

Ein undurchsichtiges Token zum Abrufen der nächsten Seite. Es ist `null` sobald die letzte Seite erreicht ist.

{% hint style="info" %}
Behandeln Sie das Fortsetzungstoken als undurchsichtig und geben Sie es unverändert zurück. Ändern Sie es nicht, speichern Sie es nicht über längere Zeiträume hinweg und verwenden Sie es nicht mit anderen Suchparametern erneut – ein Token ist nur für genau die Abfrage gültig, mit der es erstellt wurde.
{% endhint %}

**`fullTextSearch`**

Gibt an, welche Art des Textabgleichs dieses Ergebnis hervorgebracht hat.

* `true` — `searchText` wurde **beliebig** innerhalb der durchsuchten Felder gefunden (Volltextsuche).
* `false` — `searchText` wurde nur mit dem **Anfang** der durchsuchten Felder abgeglichen (Präfixsuche).

Das Feld ist auch vorhanden, wenn kein `searchText` angegeben wurde; in diesem Fall ist es `false` .

{% hint style="info" %}
`fullTextSearch` ist ab SCEPman 3.2 verfügbar. SCEPman 3.1 lässt es aus und führt immer eine Präfixsuche durch.
{% endhint %}

### Suchverhalten

#### **Volltextsuche vs. Präfixsuche**

SCEPman wählt die Suchstrategie automatisch aus. Die Auswahl der Strategie kann sich mit zukünftigen SCEPman-Versionen ändern und hängt insbesondere von der Anzahl der Zertifikate in Ihrer Umgebung ab.

* Bei `"fullTextSearch": true`verwendet SCEPman einen Teilzeichenfolgenabgleich ohne Beachtung der Groß- und Kleinschreibung für Seriennummer, Antragsteller, SANs, UPN, Anforderer, Widerrufer und Zertifikatstyp. **Teilzeichenfolgenabgleich** für Seriennummer, Antragsteller, SANs, UPN, Anforderer, Widerrufer und Zertifikatstyp.
* Bei  `"fullTextSearch": false`erfolgt der Abgleich nur am **Anfang** eines Feldes. Abgeglichen werden Seriennummer, UPN, Anforderer, Widerrufer und Antragsteller. Die Suche nach dem Antragsteller umfasst sowohl den rohen Antragstellerwert als auch den RDN „Common Name“, z. B. würde die Suche nach `device01` ein Zertifikat mit dem Antragsteller `CN=device01`.

{% hint style="warning" %}
Da API-Clients die verwendete Strategie nicht steuern können, sollten Sie sich nicht auf eine bestimmte Strategie verlassen und beide Arten von Zertifikatsmengen unterstützen können.&#x20;
{% endhint %}

### Fehlerantwort

#### **Ungültiges Fortsetzungstoken**

```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
}
```

Der Fehler mit errorCode 4014 tritt auf, wenn ein Fortsetzungstoken nicht interpretiert werden kann. Wiederholen Sie die Suche ab der ersten Seite ohne Fortsetzungstoken.

## **Widerruf-API**

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

Widerruft ein durch seine Seriennummer identifiziertes Zertifikat.

Der Anforderungstext enthält:

* `revocationReason` - eine Ganzzahl für den Widerrufsgrund. Mögliche Werte finden Sie in der folgenden Tabelle.
* `revoker` *(optional)* – eine frei wählbare Kennung für die Person oder das System, die bzw. das die Sperrung beantragt

{% hint style="info" %}
Falls angegeben, empfehlen wir, für das Feld „revoker“ den UPN zu verwenden. Andernfalls wird der UPN des angemeldeten Benutzers verwendet. Auch wenn ein Wert angegeben ist, wird der UPN des angemeldeten Benutzers weiterhin in der Form „{revoker} through API user ${logged on user}“ hinzugefügt.

Dieser Wert wird für die Überwachung und in Suchvorgängen verwendet.
{% endhint %}

### **Beispiel**

```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"
  }'
```

#### **Erfolgreiche Antwort**

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

#### **Zertifikat nicht gefunden**

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

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

#### **Bereits gesperrt**

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

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

### Unterstützte Sperrgründe

Die API unterstützt die Sperrgründe, die in [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280#section-5.3.1):

| Wert | Sperrgrund                                   |
| ---- | -------------------------------------------- |
| 0    | Nicht angegeben                              |
| 1    | Schlüssel kompromittiert                     |
| 2    | Zertifizierungsstelle kompromittiert         |
| 3    | Zugehörigkeit geändert                       |
| 4    | Ersetzt                                      |
| 5    | Betrieb eingestellt                          |
| 6    | Zertifikat gesperrt                          |
| 8    | Aus CRL entfernen                            |
| 9    | Berechtigung entzogen                        |
| 10   | Attributzertifizierungsstelle kompromittiert |


---

# 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/de/zertifikatsverwaltung/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.
