> 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/pt/gestao-de-certificados/api-rest-de-gestao.md). # API REST de gestão {% hint style="warning" %} Apenas para a SCEPman Enterprise Edition Aplicável à versão 3.1 e superior {% endhint %} A API de Gestão fornece acesso administrativo aos certificados emitidos no SCEPman. Destina-se a fluxos de trabalho de gestão e operacionais, como localizar certificados e revogá-los quando necessário. Estes endpoints estão disponíveis em `/api/manage` e requerem um utilizador autenticado com a função **Manage.All** no SCEPman-api. {% hint style="info" %} Se atualizar a partir de uma versão anterior do SCEPman, é possível que ainda não tenha a função Manage.All. Execute `Complete-SCEPmanInstallation` novamente numa Cloud Shell para a adicionar automaticamente à sua aplicação SCEPman-api. {% endhint %} ### Autenticação A API usa autenticação Entra. A forma mais fácil de autenticar é muitas vezes a Microsoft Authentication Library (MSAL). Uma forma de obter um token bearer para a Management API é com a Azure CLI. O valor necessário para o parâmetro \`--resource\` é o URI do ID da aplicação do registo da sua SCEPman-api (normalmente o ID da aplicação precedido por `api://`). ```bash az account get-access-token --resource api://[APPLICATION-ID] --query accessToken --output tsv ``` Por exemplo: ```bash TOKEN=$(az account get-access-token \ --resource api://16b6a4d1-0a20-4b41-bf58-12783034cad3 \ --query accessToken \ --output tsv) ``` Pode então usar esse token nas chamadas da 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 Pesquisa **`GET /api/manage/search`** Pesquisa os certificados emitidos e devolve um conjunto de resultados paginado. #### Parâmetros de pesquisa **`searchText`** Termo de pesquisa em texto livre usado para encontrar certificados correspondentes. Normalmente é usado para pesquisas baseadas em substring, por exemplo, correspondência do requerente ou de outros metadados pesquisáveis do certificado. **`pageSize`** Número máximo de certificados devolvidos numa única página de resposta. * Padrão: 50 **`continuationToken`** Token de paginação opcional usado para pedir a página seguinte de resultados.\ Devolva o `continuationToken` devolvido por uma resposta de pesquisa anterior para continuar a obter mais certificados. **`certValidity`** Filtra certificados pelo estado de validade. * Padrão: `Any` Os valores válidos são `Any`, `Active`, `Expired`, `Revoked`. **`certType`** Filtra certificados pelo tipo de certificado. * Padrão: `Any` Isto pode ser usado para restringir o conjunto de resultados a categorias específicas de certificados. Os valores válidos são `Static`, `DC`, `User`, `Device`, e `Any`. **`Sources`** Filtra certificados pelo endpoint através do qual foram emitidos. Pode especificar este filtro várias vezes, uma vez por origem. * Padrão: Sem restrição Os valores válidos são apresentados na tabela abaixo, deve especificar a origem usando os respetivos valores inteiros: | Origem | Valor | | ----------------- | --------------------------------------------------- | | CertificateMaster | 0 | | Intune | 1 ou 9 (use ambos para garantir que encontra todos) | | Static | 3 | | StaticAAD | 4 | | Jamf | 5 | | DomainController | 6 | | API | 7 | | RadiusAPI | 8 | | Active Directory | 10 | A resposta é uma lista paginada de registos de certificados, mais um token de continuação para obter a página seguinte. **Exemplo** ```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" ``` **Resposta de exemplo** ```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": "..." } ``` ### **API de Revogação** **`PATCH /api/manage/revoke/{serialNumber}`** Revoga um certificado identificado pelo seu número de série. O corpo do pedido contém: * `revocationReason` - um inteiro para o motivo da revogação. Consulte a tabela abaixo para os valores possíveis * `revoker` *(opcional)* - um identificador em texto livre para a pessoa ou sistema que solicita a revogação {% hint style="info" %} Se especificado, recomendamos usar o UPN para o campo revoker. Se não for especificado, será usado o UPN do utilizador autenticado. Mesmo que seja especificado, o UPN do utilizador autenticado continua a ser adicionado na forma "{revoker} through API user ${logged on user}". Este valor é usado para auditoria e nas pesquisas. {% endhint %} **Exemplo** ```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" }' ``` **Resposta bem-sucedida** ```http HTTP/1.1 200 OK ``` **Certificado não encontrado** ```http HTTP/1.1 404 Not Found Content-Type: application/json ``` ```json { "errorMessage": "Certificado não encontrado.", "errorCode": 7012 } ``` **Já revogado** ```http HTTP/1.1 409 Conflict Content-Type: application/json ``` ```json { "errorMessage": "O certificado já está revogado.", "errorCode": 5013 } ``` #### Motivos de revogação suportados A API suporta os motivos de revogação especificados em [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280#section-5.3.1): | Valor | Motivo da revogação | | ----- | -------------------- | | 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.scepman.com/pt/gestao-de-certificados/api-rest-de-gestao.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.