# APIを更新する

`PATCH /v1/apis/{api_id}` · 権限 `apis:write`

JSONマージパッチでAPIを更新します（RFC 7396、`application/merge-patch+json`）。送信したフィールドは変更され、省略したフィールドはそのままです。`If-Match`が必須です。`key`と`identifier`は作成後に変更することはできず、システムAPIは変更できません。何も変更しないパッチは何も書き込まず、バージョンは保持されます。

## リクエスト

| パラメータ | 入力 | 説明 |
|---|---|---|
| `api_id` | path | APIのID。 |
| `If-Match` | header | 最後の読み取り時の`ETag`（必須）。 |

ボディ: 下記の書き込み可能なフィールドのいずれか（すべてオプション）。フィールドは`null`で削除することはできません。

| フィールド | タイプ | 必須 | 説明 |
|---|---|---|---|
| `key` | string | いいえ | 安定した設定キー、`^[a-z0-9_-]{1,64}$`。変更不可。 |
| `identifier` | string | いいえ | トークンオーディエンス: httpsURL（クエリまたはフラグメントなし）または`urn:<nid>:<nss>`。正規形式で保存されます。変更不可。`urn:idp:`ネームスペースは予約されています。 |
| `name` | string | いいえ | 1～128文字。 |
| `access_token_lifetime_s` | integer | いいえ | 60～86400。デフォルト3600（`mcp_profile`を使用する場合は600）。 |
| `token_format` | string | いいえ | `jwt`（デフォルト）または`opaque`。 |
| `rbac_mode` | string | いいえ | ロールと権限がトークンに反映される方法: `claims`（デフォルト）は`permissions`と`org_permissions`を追加します。`off`はどちらも追加しません（`org_roles`は引き続き追加されます）。`enforce`はそれらを追加し、さらに付与されるスコープをユーザーの有効な権限に制限します。 |
| `allow_offline_access` | boolean | いいえ | デフォルト`true`。 |
| `require_resource_indicator` | boolean | いいえ | デフォルト`false`（`mcp_profile`を使用する場合は`true`）。 |
| `dpop_required` | boolean | いいえ | デフォルト`false`。 |
| `mcp_profile` | boolean | いいえ | httpsの`identifier`と`require_resource_indicator: true`が必要です。 |
| `first_party_access` | string | いいえ | `all`（デフォルト）または`granted_only`。 |
| `introspection_applications` | array | いいえ | このAPIのトークンをイントロスペクトできるアプリケーション(`app_…`)、最大50個、重複なし。同じ環境の`web`および`m2m`アプリケーションのみ。リストは全体として置き換えられます。`[]`は空にし、`null`は拒否されます。 |

### イントロスペクトアプリケーション

イントロスペクトエンドポイント(`POST <issuer>/oauth2/introspect`、RFC 7662)は、アクセストークンに対して、トークンが発行されたアプリケーション、またはトークンの`aud`で指定されたAPIの`introspection_applications`リストにあるアプリケーションの2つの呼び出し元にのみ`active: true`で応答します。他のすべての呼び出し元は`active: false`を取得するため、APIは互いのトークンを読むことができません。同じ環境の機密アプリケーション(`web`、`m2m`)のみをリストできます。リストはセットとして保存され、ID順で返されます。一時停止されたアプリケーションはリストに残りますが、イントロスペクトはできません。システムAPIのリストは書き込みできません。

## レスポンス

`200 OK`と新しい`ETag`:

```json
{
  "id": "api_01h455vb4pex5vsknk084sn02q",
  "key": "orders",
  "identifier": "https://api.example.com/orders",
  "name": "Orders API",
  "is_system": false,
  "access_token_lifetime_s": 3600,
  "token_format": "jwt",
  "rbac_mode": "off",
  "allow_offline_access": true,
  "require_resource_indicator": false,
  "dpop_required": false,
  "mcp_profile": false,
  "first_party_access": "all",
  "introspection_applications": ["app_01h455vb4pex5vsknk084sn02r"],
  "created_at": "2026-10-05T12:00:00Z",
  "updated_at": "2026-10-05T12:00:00Z"
}
```

## エラー

| HTTP | code | 情況 |
|---|---|---|
| 400 | `unknown_field` | パッチに読み取り専用または不明なフィールドが含まれています。 |
| 404 | `not_found` | この環境にそのようなAPIはありません。 |
| 409 | `conflict` | APIはシステムAPIです。 |
| 412 | `precondition_failed` | `If-Match`が現在のバージョンと一致しません。 |
| 415 | `unsupported_media_type` | コンテンツタイプが`application/merge-patch+json`ではありません。 |
| 422 | `validation_failed` | 値が無効であるか、フィールドが`null`に設定されているか、`key` / `identifier`が変更されました。 |
| 422 | `validation_failed` | `introspection_applications`アイテムがこの環境に存在しない(`unknown_application`)、機密ではない(`not_confidential`)、重複している(`duplicate`)、または`app_…` IDではありません(`invalid_value`)。ポインタはリクエスト内のインデックスを名付けます。 |
| 428 | `precondition_required` | `If-Match`が欠落しています。 |

## 例

```bash
curl -X PATCH https://api.eu.keenauth.com/v1/apis/api_01h455vb4pex5vsknk084sn02q \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "1"' \
  -d '{"access_token_lifetime_s":900}'
```