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

# API REST de administración

{% hint style="warning" %}
Solo en SCEPman Enterprise Edition

Aplicable a la versión 3.1 y posteriores
{% endhint %}

La API de administración proporciona acceso administrativo a los certificados emitidos en SCEPman. Está diseñada para flujos de trabajo de administración y operaciones, como localizar certificados y revocarlos cuando sea necesario.

Estos puntos de conexión están disponibles en `/api/manage` y requieren un usuario autenticado con el rol **Manage.All** en SCEPman-api.

{% hint style="info" %}
Si actualizas desde una versión anterior de SCEPman, es posible que todavía no tengas el rol Manage.All. Ejecuta `Complete-SCEPmanInstallation` de nuevo en una consola de nube para agregarlo automáticamente a la aplicación SCEPman-api.
{% endhint %}

## Autenticación

La API usa la autenticación de Entra. La forma más sencilla de autenticarse suele ser mediante Microsoft Authentication Library (MSAL).

Una forma de obtener un token de portador para la API de administración es usar Azure CLI. El valor necesario para el parámetro \`--resource\` es el URI del ID de aplicación del registro de aplicaciones de SCEPman-api (normalmente, el ID de aplicación precedido por `api://`).

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

Por ejemplo:

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

A continuación, puedes usar ese token en las llamadas a la 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 búsqueda

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

Busca certificados emitidos y devuelve un conjunto de resultados paginado.

### Parámetros de búsqueda

**`searchText`**

Término de búsqueda de texto libre que se usa para encontrar certificados coincidentes. Normalmente, se utiliza para búsquedas por subcadenas, por ejemplo, para encontrar coincidencias en el solicitante u otros metadatos consultables del certificado.

**`pageSize`**

Número máximo de certificados que se devuelven en una sola página de respuesta.

* Valor predeterminado: 50

**`continuationToken`**

Token de paginación opcional que se usa para solicitar la página siguiente de resultados.\
Devuelve el valor de `continuationToken` que devolvió una respuesta de búsqueda anterior para seguir obteniendo más certificados.

**`certValidity`**

Filtra los certificados según su estado de validez.

* Valor predeterminado: `Any`

Los valores válidos son `Any`, `Active`, `Expired`, `Revoked`.

**`certType`**

Filtra los certificados según su tipo.

* Valor predeterminado: `Any`

Esto permite restringir el conjunto de resultados a categorías específicas de certificados. Los valores válidos son `Static`, `DC`, `User`, `Device` y `Any`.

**`Sources`**

Filtra los certificados según el endpoint por el que se hayan emitido. Puedes especificar este filtro varias veces, una por cada origen.

* Valor predeterminado: sin restricciones

Los valores válidos se muestran en la tabla siguiente; debes especificar el origen con su valor entero:

| Origen            | Valor                                                |
| ----------------- | ---------------------------------------------------- |
| CertificateMaster | 0                                                    |
| Intune            | 1 o 9 (usa ambos para asegurarte de encontrar todos) |
| Static            | 3                                                    |
| StaticAAD         | 4                                                    |
| Jamf              | 5                                                    |
| DomainController  | 6                                                    |
| API               | 7                                                    |
| RadiusAPI         | 8                                                    |
| Active Directory  | 10                                                   |

### **Ejemplo**

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

#### **Respuesta de ejemplo**

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

### **Campos de la respuesta**

**`items`**

Los certificados de la página actual.

**`continuationToken`**

Un token opaco para obtener la página siguiente. Es `null` cuando se llega a la última página.

{% hint style="info" %}
Trata el token de continuación como opaco y envíalo de vuelta sin modificarlo. No lo modifiques, no lo guardes durante períodos prolongados ni lo reutilices con otros parámetros de búsqueda: el token solo es válido para la consulta exacta que lo generó.
{% endhint %}

**`fullTextSearch`**

Indica qué tipo de coincidencia de texto produjo este resultado.

* `true` — `searchText` se encontraba en **cualquier parte** de los campos de búsqueda (búsqueda de texto completo).
* `false` — `searchText` solo se buscaba al **principio** de los campos de búsqueda (búsqueda por prefijo).

El campo también está presente cuando no se proporcionó `searchText` ; en ese caso, su valor es `false` .

{% hint style="info" %}
`fullTextSearch` Está disponible a partir de SCEPman 3.2. SCEPman 3.1 lo omite y siempre realiza una búsqueda por prefijo.
{% endhint %}

### Comportamiento de búsqueda

#### **Búsqueda de texto completo frente a búsqueda por prefijo**

SCEPman elige automáticamente la estrategia de búsqueda, y la selección de la estrategia puede cambiar en futuras versiones de SCEPman, especialmente en función del número de certificados de su entorno.

* Con `"fullTextSearch": true`, SCEPman realiza una búsqueda de **subcadenas** sin distinguir entre mayúsculas y minúsculas en el número de serie, el sujeto, los SAN, el UPN, el solicitante, el revocador y el tipo de certificado.
* Con  `"fullTextSearch": false`, la búsqueda solo encuentra coincidencias al **principio** de un campo. Los campos en los que se buscan coincidencias son el número de serie, el UPN, el solicitante, el revocador y el sujeto. La búsqueda del sujeto incluye tanto el sujeto sin procesar como el RDN del nombre común (Common Name); por ejemplo, buscar `device01` encontraría un certificado con el sujeto `CN=device01`.

{% hint style="warning" %}
Como los clientes de la API no pueden controlar la estrategia específica que se utiliza, no debe confiar en que se use una estrategia concreta y debe poder gestionar ambos volúmenes de certificados.&#x20;
{% endhint %}

### Respuesta de error

#### **Token de continuación no válido**

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

El error con errorCode 4014 se produce cuando no se puede interpretar un token de continuación. Repita la búsqueda desde la primera página sin un token de continuación.

## **API de revocación**

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

Revoca un certificado identificado por su número de serie.

El cuerpo de la solicitud contiene:

* `revocationReason` - un número entero que indica el motivo de la revocación. Consulte la tabla siguiente para ver los valores posibles.
* `revoker` *(opcional)* - un identificador de texto libre para la persona o el sistema que solicita la revocación

{% hint style="info" %}
Si se especifica, recomendamos usar el UPN en el campo revoker. Si no se especifica, se usará el UPN del usuario que inició sesión. Aunque se especifique, el UPN del usuario que inició sesión también se añade en el formulario "{revoker} through API user ${logged on user}".

Este valor se usa para auditorías y búsquedas.
{% endhint %}

### **Ejemplo**

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

#### **Respuesta correcta**

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

#### **Certificado no encontrado**

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

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

#### **Ya revocado**

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

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

### Motivos de revocación admitidos

La API admite los motivos de revocación especificados en [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280#section-5.3.1):

| Valor | Motivo de revocación                    |
| ----- | --------------------------------------- |
| 0     | Sin especificar                         |
| 1     | Compromiso de clave                     |
| 2     | Compromiso de la CA                     |
| 3     | Cambio de afiliación                    |
| 4     | Sustituido                              |
| 5     | Cese de operaciones                     |
| 6     | Certificado retenido                    |
| 8     | Eliminar de la CRL                      |
| 9     | Privilegios retirados                   |
| 10    | Compromiso de la autoridad de atributos |


---

# 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/es/administracion-de-certificados/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.
