> 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/fr/gestion-des-certificats/management-rest-api.md).

# API REST de gestion

{% hint style="warning" %}
Édition Enterprise de SCEPman uniquement

Applicable à partir de la version 3.1
{% endhint %}

L’API de gestion permet d’accéder à titre administratif aux certificats émis par SCEPman. Elle est destinée aux opérations de gestion et d’exploitation, comme la recherche de certificats et leur révocation si nécessaire.

Ces points de terminaison sont disponibles sous `/api/manage` et nécessitent un utilisateur authentifié disposant du rôle **Manage.All** dans SCEPman-api.

{% hint style="info" %}
Si vous effectuez une mise à jour depuis une version antérieure de SCEPman, il se peut que vous ne disposiez pas encore du rôle Manage.All. Exécutez à nouveau `Complete-SCEPmanInstallation` dans un shell cloud afin de l’ajouter automatiquement à votre application SCEPman-api.
{% endhint %}

## Authentification

L’API utilise l’authentification Entra. La bibliothèque d’authentification Microsoft (MSAL) est souvent le moyen le plus simple de s’authentifier.

Vous pouvez notamment obtenir un jeton Bearer pour l’API de gestion à l’aide de l’interface de ligne de commande Azure. La valeur requise pour le paramètre \`--resource\` est l’URI d’ID d’application de l’inscription d’application SCEPman-api (généralement son ID d’application précédé de `api://`).

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

Par exemple :

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

Vous pouvez ensuite utiliser ce jeton dans les appels à l’API :

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

## API de recherche

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

Recherche les certificats émis et renvoie un ensemble de résultats paginé.

### Paramètres de recherche

**`searchText`**

Terme de recherche en texte libre utilisé pour trouver les certificats correspondants. Il sert généralement aux recherches par sous-chaîne, par exemple pour rechercher le demandeur ou d’autres métadonnées consultables du certificat.

**`pageSize`**

Nombre maximal de certificats renvoyés dans une seule page de résultats.

* Valeur par défaut : 50

**`continuationToken`**

Jeton de pagination facultatif permettant de demander la page de résultats suivante.\
Renvoyez le `continuationToken` renvoyé par une réponse de recherche précédente pour continuer à récupérer des certificats.

**`certValidity`**

Filtre les certificats selon leur état de validité.

* Valeur par défaut : `Any`

Les valeurs valides sont `Any`, `Active`, `Expired`, `Revoked`.

**`certType`**

Filtre les certificats selon leur type.

* Valeur par défaut : `Any`

Ce paramètre permet de limiter l’ensemble de résultats à des catégories de certificats spécifiques. Les valeurs valides sont `Static`, `DC`, `User`, `Device` et `Any`.

**`Sources`**

Filtre les certificats selon le point de terminaison par lequel ils ont été émis. Vous pouvez spécifier ce filtre plusieurs fois, une fois par source.

* Par défaut : aucune restriction

Les valeurs valides sont indiquées dans le tableau ci-dessous. Vous devez spécifier la source à l’aide de sa valeur entière :

| Source            | Valeur                                                         |
| ----------------- | -------------------------------------------------------------- |
| CertificateMaster | 0                                                              |
| Intune            | 1 ou 9 (utilisez les deux pour être sûr de toutes les trouver) |
| Static            | 3                                                              |
| StaticAAD         | 4                                                              |
| Jamf              | 5                                                              |
| DomainController  | 6                                                              |
| API               | 7                                                              |
| RadiusAPI         | 8                                                              |
| Active Directory  | 10                                                             |

### **Exemple**

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

#### **Exemple de réponse**

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

### **Champs de la réponse**

**`items`**

Les certificats de la page actuelle.

**`continuationToken`**

Un jeton opaque permettant de récupérer la page suivante. Il vaut `null` lorsque la dernière page a été atteinte.

{% hint style="info" %}
Considérez le jeton de continuation comme opaque et renvoyez-le sans le modifier. Ne le modifiez pas, ne le conservez pas pendant de longues périodes et ne le réutilisez pas avec des paramètres de recherche différents : un jeton n’est valide que pour la requête exacte qui l’a généré.
{% endhint %}

**`fullTextSearch`**

Indique le type de correspondance textuelle ayant produit ce résultat.

* `true` — `searchText` a été trouvé **n’importe où** dans les champs recherchés (recherche en texte intégral).
* `false` — `searchText` a été recherché uniquement au **début** des champs recherchés (recherche par préfixe).

Le champ est également présent lorsqu’aucun `searchText` n’a été fourni ; il vaut `false` dans ce cas.

{% hint style="info" %}
`fullTextSearch` est disponible à partir de SCEPman 3.2. SCEPman 3.1 ne le renvoie pas et effectue toujours une recherche par préfixe.
{% endhint %}

### Comportement de la recherche

#### **Recherche en texte intégral ou recherche par préfixe**

SCEPman choisit automatiquement la stratégie de recherche. Celle-ci peut évoluer dans les futures versions de SCEPman, notamment en fonction du nombre de certificats dans votre environnement.

* Pour `"fullTextSearch": true`, SCEPman effectue une recherche **de sous-chaîne** insensible à la casse dans le numéro de série, le sujet, les SAN, l’UPN, le demandeur, le révocateur et le type de certificat.
* Pour  `"fullTextSearch": false`, la recherche ne porte que sur le **début** d’un champ. Les champs recherchés sont le numéro de série, l’UPN, le demandeur, le révocateur et le sujet. La recherche dans le sujet porte à la fois sur le sujet brut et sur le RDN Common Name. Par exemple, la recherche de `device01` trouverait un certificat dont le sujet est `CN=device01`.

{% hint style="warning" %}
Comme les clients de l’API ne peuvent pas contrôler la stratégie utilisée, vous ne devez pas compter sur une stratégie particulière et devez pouvoir gérer les deux volumes de certificats.&#x20;
{% endhint %}

### Réponse d’erreur

#### **Jeton de continuation non valide**

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

L’erreur avec errorCode 4014 se produit lorsque le jeton de continuation ne peut pas être interprété. Recommencez la recherche depuis la première page, sans jeton de continuation.

## **API de révocation**

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

Révoque un certificat identifié par son numéro de série.

Le corps de la requête contient :

* `revocationReason` - un entier indiquant le motif de révocation. Consultez le tableau ci-dessous pour connaître les valeurs possibles
* `revoker` *(facultatif)* - un identifiant en texte libre désignant la personne ou le système demandant la révocation

{% hint style="info" %}
Si cette valeur est spécifiée, nous vous recommandons d’utiliser l’UPN pour le champ du demandeur de révocation. Sinon, l’UPN de l’utilisateur connecté sera utilisé. Même si cette valeur est spécifiée, l’UPN de l’utilisateur connecté est également ajouté dans le formulaire « {revoker} through API user ${logged on user} ».

Cette valeur est utilisée à des fins d’audit et dans les recherches.
{% endhint %}

### **Exemple**

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

#### **Réponse en cas de réussite**

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

#### **Certificat introuvable**

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

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

#### **Déjà révoqué**

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

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

### Motifs de révocation pris en charge

L’API prend en charge les motifs de révocation spécifiés dans [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280#section-5.3.1):

| Valeur | Motif de révocation                          |
| ------ | -------------------------------------------- |
| 0      | Non spécifié                                 |
| 1      | Compromission de clé                         |
| 2      | Compromission de l’autorité de certification |
| 3      | Changement d’affiliation                     |
| 4      | Remplacé                                     |
| 5      | Cessation d’activité                         |
| 6      | Certificat suspendu                          |
| 8      | Retirer de la liste de révocation            |
| 9      | Retrait de privilèges                        |
| 10     | Compromission de l’autorité d’attribut       |


---

# 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/fr/gestion-des-certificats/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.
