> 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 für Version 3.1 und höher {% endhint %} Die Management-API bietet administrativen Zugriff auf ausgestellte Zertifikate in SCEPman. Sie ist für Verwaltungs- und Betriebsabläufe vorgesehen, z. B. zum Auffinden von Zertifikaten und zum Widerrufen, wenn nötig. Diese Endpunkte sind unter `/api/manage` und erfordern einen authentifizierten Benutzer mit der **Manage.All** Rolle in SCEPman-api. {% hint style="info" %} Wenn Sie von einer früheren SCEPman-Version aktualisieren, verfügen Sie möglicherweise noch nicht über die Rolle Manage.All. Führen Sie `Complete-SCEPmanInstallation` in einer Cloud Shell erneut aus, um sie automatisch zu Ihrer SCEPman-api-Anwendung hinzuzufügen. {% endhint %} ### Authentifizierung Die API verwendet Entra-Authentifizierung. Der einfachste Weg zur Authentifizierung ist oft die Microsoft Authentication Library (MSAL). Eine Möglichkeit, ein Bearer-Token für die Management-API zu erhalten, ist über die Azure CLI. Der erforderliche Wert für den Parameter \`--resource\` ist die Application-ID-URI Ihrer SCEPman-api-App-Registrierung (normalerweise ihre Application ID mit dem Präfix `api://`). ```bash az account get-access-token --resource api://[APPLICATION-ID] --query accessToken --output tsv ``` Zum Beispiel: ```bash TOKEN=$(az account get-access-token \ --resource api://16b6a4d1-0a20-4b41-bf58-12783034cad3 \ --query accessToken \ --output tsv) ``` Sie können dieses Token dann 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, der verwendet wird, um passende Zertifikate zu finden. Dies wird typischerweise für substring-basierte Abfragen verwendet, zum Beispiel zum Abgleich des Anforderers oder anderer durchsuchbarer Zertifikatsmetadaten. **`pageSize`** Maximale Anzahl von Zertifikaten, die in einer einzelnen Antwortseite zurückgegeben werden. * Standard: 50 **`continuationToken`** Optionales Paginierungstoken, das verwendet wird, um die nächste Ergebnisseite anzufordern.\ Geben Sie das `continuationToken` von einer vorherigen Suchantwort zurückgegebene Token zurück, um weitere Zertifikate abzurufen. **`certValidity`** Filtert Zertifikate nach ihrem Gültigkeitsstatus. * Standard: `Beliebig` Gültige Werte sind `Beliebig`, `Aktiv`, `Abgelaufen`, `Widerrufen`. **`certType`** Filtert Zertifikate nach Zertifikatstyp. * Standard: `Beliebig` Hiermit kann die Ergebnismenge auf bestimmte Zertifikatskategorien eingeschränkt werden. Gültige Werte sind `Static`, `DC`, `Benutzer`, `Gerät`und `Beliebig`. **`Quellen`** Filtert Zertifikate nach dem Endpunkt, über den sie ausgestellt wurden. Sie können diesen Filter mehrmals angeben, einmal pro Quelle. * Standard: Keine Einschränkung Gültige Werte sind in der folgenden Tabelle aufgeführt, Sie müssen die Quelle anhand ihrer Ganzzahlwerte angeben: | Quelle | Wert | | ----------------- | ----------------------------------------------------------------------------- | | CertificateMaster | 0 | | Intune | 1 oder 9 (verwenden Sie beide, um sicherzustellen, dass alle gefunden werden) | | Static | 3 | | StaticAAD | 4 | | Jamf | 5 | | DomainController | 6 | | API | 7 | | RadiusAPI | 8 | | Active Directory | 10 | Die Antwort ist eine paginierte Liste von Zertifikatsdatensätzen plus ein Fortsetzungstoken zum Abrufen der nächsten Seite. **Beispiel** ```bash curl -X GET "https://scepman.contoso.com/api/manage/search?searchText=507AEAC03CCEF83F106914418D9222E466A629C1&pageSize=10&certValidity=Any&certType=Any" \ -H "Authorization: Bearer " \ -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": "..." } ``` ### **Widerrufs-API** **`PATCH /api/manage/revoke/{serialNumber}`** Widerruft ein Zertifikat, das durch seine Seriennummer identifiziert wird. Der Anforderungstext enthält: * `revocationReason` - eine Ganzzahl für den Widerrufsgrund. Siehe die folgende Tabelle für mögliche Werte * `revoker` *(optional)* - ein Freitext-Bezeichner für die Person oder das System, das den Widerruf anfordert {% hint style="info" %} Falls angegeben, empfehlen wir die Verwendung der UPN für das Feld revoker. Falls nicht angegeben, wird die UPN des angemeldeten Benutzers verwendet. Selbst wenn angegeben, wird die UPN des angemeldeten Benutzers weiterhin in der Form "{revoker} über API-Benutzer ${logged on user}" hinzugefügt. Dieser Wert wird für Prüfzwecke und in Suchanfragen verwendet. {% endhint %} **Beispiel** ```bash curl -X PATCH "https://scepman.contoso.com/api/manage/revoke/ABC123" \ -H "Authorization: Bearer " \ -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": "Zertifikat nicht gefunden.", "errorCode": 7012 } ``` **Bereits widerrufen** ```http HTTP/1.1 409 Conflict Content-Type: application/json ``` ```json { "errorMessage": "Das Zertifikat ist bereits widerrufen.", "errorCode": 5013 } ``` #### Unterstützte Widerrufsgründe Die API unterstützt die in [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280#section-5.3.1): | Wert | Widerrufsgrund | | ---- | ------------------------- | | 0 | Nicht angegeben | | 1 | Schlüsselkompromittierung | | 2 | CA-Kompromittierung | | 3 | Zugehörigkeit geändert | | 4 | Ersetzt | | 5 | Betrieb eingestellt | | 6 | Zertifikat in Sperre | | 8 | Aus CRL entfernen | | 9 | Privileg entzogen | | 10 | AA-Kompromittierung | --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.scepman.com/de/zertifikatsverwaltung/management-rest-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.