> 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/ja/zheng-ming-shu-guan-li/management-rest-api.md).

# 管理用 REST API

{% hint style="warning" %}
SCEPman Enterprise Edition のみ

バージョン 3.1 以降に適用
{% endhint %}

Management API を使用すると、SCEPman で発行された証明書に管理者としてアクセスできます。証明書の検索や、必要に応じた失効など、管理および運用のワークフローを目的としています。

これらのエンドポイントは次のパスで利用できます。 `/api/manage` また、SCEPman-api の **Manage.All** ロールを持つ認証済みユーザーが必要です。

{% hint style="info" %}
以前のバージョンの SCEPman からアップデートした場合、Manage.All ロールがまだ設定されていないことがあります。クラウドシェルで `Complete-SCEPmanInstallation` を再度実行すると、SCEPman-api アプリケーションにロールが自動的に追加されます。
{% endhint %}

## 認証

この API は Entra 認証を使用します。多くの場合、Microsoft Authentication Library（MSAL）を使うのが最も簡単な認証方法です。

Management API のベアラートークンを取得する方法の 1 つは、Azure CLI を使うことです。\`--resource\` パラメーターに指定する値は、SCEPman-api アプリ登録のアプリケーション ID URI です（通常は、アプリケーション ID の前に `api://`).

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

例：

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

その後、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

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

発行済み証明書を検索し、ページ分割された結果を返します。

### 検索パラメーター

**`searchText`**

一致する証明書を検索するためのフリーテキスト検索語です。通常、要求者やその他の検索可能な証明書メタデータなどを部分一致で検索するために使用します。

**`pageSize`**

1 ページの応答で返される証明書の最大数です。

* 既定値：50

**`continuationToken`**

次の結果ページを要求するための任意のページネーショントークンです。\
前回の検索応答で返された `continuationToken` を渡すと、続きの証明書を取得できます。

**`certValidity`**

証明書の有効状態でフィルターします。

* 既定値： `Any`

有効な値： `Any`, `Active`, `Expired`, `Revoked`.

**`certType`**

証明書の種類でフィルターします。

* 既定値： `Any`

特定の証明書カテゴリに結果を絞り込むために使用できます。有効な値は次のとおりです。 `Static`, `DC`, `User`, `Device`、および `Any`.

**`Sources`**

証明書が発行されたエンドポイントで証明書を絞り込みます。このフィルターは、ソースごとに複数回指定できます。

* デフォルト: 制限なし

有効な値を以下の表に示します。ソースは整数値で指定してください。

| ソース               | 値                           |
| ----------------- | --------------------------- |
| CertificateMaster | 0                           |
| Intune            | 1 または 9（すべてを確実に見つけるには両方を使用） |
| Static            | 3                           |
| StaticAAD         | 4                           |
| Jamf              | 5                           |
| DomainController  | 6                           |
| API               | 7                           |
| RadiusAPI         | 8                           |
| Active Directory  | 10                          |

### **例**

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

#### **レスポンスの例**

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

### **レスポンスフィールド**

**`items`**

現在のページに含まれる証明書。

**`continuationToken`**

次のページを取得するための不透明なトークンです。 `null` 最終ページに達すると、この値になります。

{% hint style="info" %}
継続トークンは不透明な値として扱い、変更せずにそのまま返送してください。変更したり、長期間保存したり、異なる検索パラメーターで再利用したりしないでください。トークンは、それを生成したクエリに対してのみ有効です。
{% endhint %}

**`fullTextSearch`**

この結果の生成に使用されたテキスト照合方式を示します。

* `true` — `searchText` が一致した **場所は問わず** 検索対象フィールド内（全文検索）。
* `false` — `searchText` は、検索対象フィールドの **先頭** とのみ一致しました（前方一致検索）。

このフィールドは、 `searchText` が指定されていない場合にも含まれます。その場合は `false` になります。

{% hint style="info" %}
`fullTextSearch` は SCEPman 3.2 以降で使用できます。SCEPman 3.1 では省略され、常に前方一致検索が実行されます。
{% endhint %}

### 検索動作

#### **全文検索と前方一致検索**

SCEPman は検索方式を自動的に選択します。方式の選択は今後の SCEPman のバージョンで変更される可能性があり、特に環境内の証明書数に応じて変わることがあります。

* の場合 `"fullTextSearch": true`、SCEPman は大文字と小文字を区別せず、 **部分文字列** をシリアル番号、サブジェクト、SAN、UPN、要求者、失効者、証明書の種類から検索します。
* の場合  `"fullTextSearch": false`、検索はフィールドの **先頭** とのみ一致します。一致対象フィールドは、シリアル番号、UPN、要求者、失効者、サブジェクトです。サブジェクト検索には、未加工のサブジェクトと Common Name RDN の両方が含まれます。たとえば、 `device01` を検索すると、サブジェクトが `CN=device01`.

{% hint style="warning" %}
API クライアントは使用される検索方式を指定できないため、特定の方式が使われることを前提とせず、どちらの証明書数にも対応できるようにしてください。&#x20;
{% endhint %}

### エラーレスポンス

#### **無効な継続トークン**

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

errorCode 4014 のエラーは、継続トークンを解釈できない場合に発生します。継続トークンを指定せずに、最初のページから検索をやり直してください。

## **失効 API**

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

シリアル番号で指定された証明書を失効させます。

リクエスト本文には次の項目が含まれます。

* `revocationReason` - 失効理由を表す整数。指定可能な値については、以下の表を参照してください。
* `revoker` *（任意）* - 失効を要求する人物またはシステムを示す自由形式の識別子

{% hint style="info" %}
指定する場合は、失効者のフィールドに UPN を使用することをお勧めします。指定しない場合は、ログオン中のユーザーの UPN が使用されます。指定した場合でも、ログオン中のユーザーの UPN は "{revoker} through API user ${logged on user}" という形式で追加されます。

この値は監査と検索に使用されます。
{% endhint %}

### **例**

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

#### **成功時のレスポンス**

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

#### **証明書が見つかりません**

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

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

#### **すでに失効済み**

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

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

### サポートされている失効理由

この API は、次に指定されている失効理由をサポートします。 [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280#section-5.3.1):

| 値  | 失効理由     |
| -- | -------- |
| 0  | 指定なし     |
| 1  | 鍵の危殆化    |
| 2  | CA の危殆化  |
| 3  | 所属の変更    |
| 4  | 置換       |
| 5  | 運用終了     |
| 6  | 証明書の保留   |
| 8  | CRL から削除 |
| 9  | 権限の取り消し  |
| 10 | AA の危殆化  |


---

# 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/ja/zheng-ming-shu-guan-li/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.
