AI Gateway設定APIを使用すると、対話型コンソールの代わりにHTTPS経由でAI Gatewayアプライアンスを設定できます。これには、アプライアンスの登録、TLS証明書管理、およびDLPとAI Guardrailsのサービス接続が含まれます。
このAPIのすべてのエンドポイント：
- HTTPS ポート
8443で使用します。APIはプレーンHTTPに対応していません。 /v1/configを起点としています。- bearer token ヘッダーに
Authorizationが必要です。
認証
APIはデフォルトで無効になっています。connecting to the appliance over SSHとしてnsadminオペレーターアカウントでログインし、enable-apiを実行することで有効にできます。APIを有効にすると、ネットワークポートが開き、アクセストークンが発行されます。
# Enable the API and generate a token with a chosen lifetime
ssh nsadmin@<appliance_ip> 'enable-api --ttl 168h'
# {
# "token": "<token>",
# "expires_at": "2026-06-10T10:00:00Z"
# }
# Disable the API again (closes the port)
ssh nsadmin@<appliance_ip> 'disable-api'
- コマンドを指定せずに
ssh nsadmin@<appliance_ip>を実行すると、インタラクティブなaig-cliコンソールが起動し、そこでenable-api --ttl 168hを直接入力できます。 - トークンは生成時にonce表示され、再度取得することはできません。安全に保存してください。
--ttlのライフタイムは、数値の後に単位サフィックスが付いた正の継続時間です —h（時間）、m（分）、またはs（秒）。1h30mのように単位を組み合わせることもできます。日（day）の単位がないため、7日間の場合は168hを使用してください。省略した場合はデフォルトで24hになります。- 有効なトークンは一度に1つのみです。APIを再度有効にすると、新しいトークンが発行され、前のトークンが無効になります。
すべてのリクエストにトークンを含めてください：
Authorization: Bearer <token>リクエスト内のトークンが欠落している、不正形式である、無効である、または有効期限が切れている場合、APIは401 Unauthorizedを返します。トークンの有効期限が切れると、disable-apiを実行するまでポートは開いたままになります。新しいトークンを生成するまで、APIは単に401を返します。
エンドポイントの概要
| Group | メソッドとパス | デスクリプション |
|---|---|---|
| Bootstrap | POST /v1/config/bootstrap | 自動登録を開始する（オプションで DLP / AI Guardrails の構成を使用） |
| Bootstrap | GET /v1/config/bootstrap | 登録ステータスの確認 |
| Certificate | GET /v1/config/certificate/status | 現在の証明書情報を取得する |
| Certificate | POST /v1/config/certificate/csr | 証明書署名リクエストを生成します |
| Certificate | POST /v1/config/certificate/install | CA署名済み証明書をインストールします |
| DLP | GET /v1/config/dlp | 現在のDLP構成を取得 |
| DLP | PUT /v1/config/dlp/ca-cert | DLPアップストリームのCA証明書をアップロードします |
| DLP | PUT /v1/config/dlp/hostconfig | DLP アップストリーム ホストを設定します。 |
| DLP | DELETE /v1/config/dlp/hostconfig | DLPホスト設定を削除します。 |
| AI Guardrails | GET /v1/config/ai-guardrails | 現在の AI Guardrails 構成を取得 |
| AI Guardrails | PUT /v1/config/ai-guardrails/ca-cert | AI Guardrails アップストリーム用の CA 証明書をアップロードする |
| AI Guardrails | PUT /v1/config/ai-guardrails/hostconfig | AI GuardrailsのアップストリームホストとOAuth認証を設定します |
| AI Guardrails | DELETE /v1/config/ai-guardrails/hostconfig | AI Guardrails ホストの設定を削除します |
Bootstrap API
自動化されたアプライアンスの登録を実行し、必要に応じて同時にDLPおよび／またはAI Guardrailsの構成を適用します。
POST /v1/config/bootstrap
提供された登録トークンを使用してアプライアンスの登録を開始し、含めたDLPまたはAI Guardrailsの構成を適用します。
Request body
| 鍵 | タイプ | 例 | デスクリプション |
|---|---|---|---|
enrollment_token | string | "eyJhbGciOi..." | 必須。登録トークン（最大2048文字）。 |
dlp | object | {"host":"https://dlp.example.com","certificate":"-----BEGIN CERTIFICATE-----..."} | オプションです。登録時に適用するDLP構成。以下の DLPオブジェクト を参照してください。 |
ai_guardrails | object | {"host":"https://llm.example.com","jwt_url":"https://auth.example.com/oauth/token"} | オプション。登録時に適用するAI Guardrailsの構成。以下のAI Guardrailsオブジェクトをご覧ください。 |
dlp object — dlpオブジェクトが存在する場合、両方のフィールドが必須です。
| 鍵 | タイプ | 例 | デスクリプション |
|---|---|---|---|
certificate | string | "-----BEGIN CERTIFICATE-----..." | 必須です。DLP アップストリーム用の PEM エンコードされた CA 証明書（最大 5,120 文字）。 |
host | string | "https://dlp.example.com" | 必須DLPアップストリームベースURL（有効なURL、最大256文字）。 |
ai_guardrails object
| 鍵 | タイプ | 例 | デスクリプション |
|---|---|---|---|
host | string | "https://llm.example.com" | 必須AI GuardrailsアップストリームベースURL（有効なURL、最大256文字）。 |
certificate | string | "-----BEGIN CERTIFICATE-----..." | オプション。AI Guardrailsアップストリーム用のPEMエンコードされたCA証明書（最大5120文字）。 |
jwt_url | string | "https://auth.example.com/oauth/token" | Optional. OAuth/JWT token endpoint (valid URL, max 1024 chars). |
client_id | string | "aig-client" | Optional. OAuth client ID (max 256 chars). |
client_secret | string | "s3cr3t" | Optional. OAuth client secret (max 10000 chars). |
scope | string | "llm.read" | Optional. OAuth scope (max 256 chars). |
Example request
POST /v1/config/bootstrap HTTP/1.1
Host: <appliance_ip>:8443
Content-Type: application/json
{
"enrollment_token": "eyJhbGciOi...",
"dlp": {
"host": "https://dlp.example.com",
"certificate": "-----BEGIN CERTIFICATE-----..."
},
"ai_guardrails": {
"host": "https://llm.example.com",
"jwt_url": "https://auth.example.com/oauth/token"
}
Success response — 202 Accepted. Enrollment runs in the background; poll the status endpoint for progress.
ブートストラップが開始されました。オプションの設定は要求されていません：
{
"status": "running"
}
ブートストラップが開始され、DLPおよびAI Guardrailsの設定が保留中です：
{
"status": "running",
"dlp": "pending",
"ai_guardrails": "pending"
}
Error response — 400 Bad Request
エンロールメントトークン（enrollment_token）がありません：
{
"err_code": "00101",
"message": "invalid format: validation error occurred in the request",
"validation_errors": [
{
"field": "enrollment_token",
"error": "enrollment_token is a required field"
}
]
}
Invalid dlp.host URL:
{
"err_code": "00101",
"message": "invalid format: validation error occurred in the request",
"validation_errors": [
{
"field": "dlp.host",
"error": "host must be a valid URL"
}
]
}
Error response — 500 Internal Server Error
ブートストラップステータスの永続化に失敗しました：
{
"err_code": "00601",
"message": "System Error"
}
GET /v1/config/bootstrap
現在の登録ステータスを返します。
| Field | タイプ | デスクリプション |
|---|---|---|
status | string | 全体的なステータス: not_started、running、completed、または failed |
dlp | string | サービス別のステータス：pending、completed、failed、または skipped |
ai_guardrails | string | サービス別のステータス：pending、completed、failed、または skipped |
オプションのDLPまたはAI Guardrailsの構成の適用に失敗しても、登録全体が失敗することはありません。
Example request
GET /v1/config/bootstrap HTTP/1.1 Host: <appliance_ip>:8443
Success response — 200 OK
Bootstrap not yet triggered:
{
"status": "not_started"
}
ブートストラップが進行中です：
{
"status": "running",
"dlp": "pending",
"ai_guardrails": "pending"
}
Bootstrap completed, no optional config requested:
{
"status": "completed"
}
Bootstrap completed, DLP and AI Guardrails both configured:
{
"status": "completed",
"dlp": "completed",
"ai_guardrails": "completed"
}
Bootstrap failed, optional steps auto-skipped:
{
"status": "failed",
"dlp": "skipped",
"ai_guardrails": "skipped"
}
証明書API
アプライアンスのゲートウェイTLS証明書を管理します。一般的なフローは、CSRを生成し、CAに署名してもらい、署名済み証明書をインストールすることです。インストールされた証明書は、アプライアンスを再起動せずに有効になります。
POST /v1/config/certificate/csr
ゲートウェイ証明書の証明書署名リクエスト（CSR）を生成します。
Request body
| 鍵 | タイプ | 例 | デスクリプション |
|---|---|---|---|
common_name | string | "gateway.example.com" | 必須です。証明書CN（最大256文字）。 |
organization | string | "Example Inc" | オプション。組織名（O）（最大256文字）。 |
organization_unit | string | "IT" | Optional. Organizational Unit (OU) (max 256 chars). |
email | string | "admin@example.com" | オプション。サブジェクトの電子メールアドレス（有効な電子メール形式）。 |
country | string | "US" | オプション。2文字の国コード（C）、正確に2文字のアルファベット。 |
state | string | "California" | オプション。州または都道府県（ST）（最大256文字）。 |
city | string | "San Jose" | オプション。市区町村（L）（最大 256 文字）。 |
key_algorithm | string | "ecdsa" | オプション。秘密鍵アルゴリズム；ecdsa、rsa、ed25519のいずれか。未設定の場合は、ecdsa（P-256）がデフォルトになります。 |
key_size | integer | 2048 | 任意です。ビット単位の RSA キーサイズ。2048、3072、4096 のいずれか。key_algorithm が rsa の場合に適用されます。 |
key_curve | string | "P256" | オプション。ECDSA曲線；P256、P384、P521のいずれか。key_algorithmがecdsaの場合に適用されます。 |
Example request
POST /v1/config/certificate/csr HTTP/1.1
Host: <appliance_ip>:8443
Content-Type: application/json
{
"common_name": "gateway.example.com",
"organization": "Example Inc",
"country": "US"
}
Success response — 200 OK
CSR生成済み：
{
"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----\n"
}
Error response — 400 Bad Request
共通名の欠落：
{
"err_code": "00101",
"message": "invalid format: validation error occurred in the request",
"validation_errors": [
{
"field": "common_name",
"error": "common_name is a required field"
}
]
}
Error response — 500 Internal Server Error
予期せぬサーバーエラー：
{
"err_code": "00601",
"message": "System Error"
}
POST /v1/config/certificate/install
ゲートウェイのCA署名済み証明書をインストールします。証明書は、最新のCSRに対して生成されたキーペアと一致している必要があります。新しい証明書は、再起動を行わずに即座に有効になります。
Request body
| 鍵 | タイプ | 例 | デスクリプション |
|---|---|---|---|
certificate | string | "-----BEGIN CERTIFICATE-----..." | 必須。PEMエンコードされたX.509証明書（最大6,500文字）。 |
Example request
POST /v1/config/certificate/install HTTP/1.1
Host: <appliance_ip>:8443
Content-Type: application/json
{
"certificate": "-----BEGIN CERTIFICATE-----..."
}
Success response — 204 No Content. Empty body.
Error response — 400 Bad Request
証明書が最大長を超えています：
{
"err_code": "00101",
"message": "invalid format: validation error occurred in the request",
"validation_errors": [
{
"field": "certificate",
"error": "certificate must be a maximum of 6,500 characters in length"
}
]
}
Error response — 403 Forbidden
証明書とキーの不一致：
{
"err_code": "00502",
"message": "forbidden: failed to install certificate"
}
Error response — 404 Not Found
アプライアンス上に秘密鍵がない場合（例：事前にCSRを生成してください）：
{
"err_code": "00301",
"message": "resource not found: failed to install certificate"
}
Error response — 500 Internal Server Error
予期せぬサーバーエラー：
{
"err_code": "00601",
"message": "System Error"
}
GET /v1/config/certificate/status
現在のゲートウェイ証明書のメタデータを返します。リクエスト ボディはありません。
Example request
GET /v1/config/certificate/status HTTP/1.1 Host: <appliance_ip>:8443
Success response — 200 OK
アクティブな証明書：
{
"status": {
"subject": "CN=gateway.example.com,OU=IT,O=Example Inc,L=San Jose,ST=California,C=US",
"issuer": "CN=Example CA,O=Example Inc",
"valid_from": "2026-01-15T00:00:00Z",
"valid_to": "2027-01-15T00:00:00Z",
"serial_number": "289797283705493259445630949940925559092",
"status": "Active"
}
}
Error response — 404 Not Found
証明書がインストールされていません：
{
"err_code": "00301",
"message": "resource not found: failed to get certificate status"
}
Error response — 500 Internal Server Error
予期せぬサーバーエラー：
{
"err_code": "00601",
"message": "System Error"
}
DLP 構成 API
DLPサービスへのアプライアンスの接続を構成します。信頼証明書とアップストリームホストは、別々のエンドポイントを通じて設定されます。DLPホスト設定では、ホストURLのみを受け入れます（OAuthフィールドはありません）。
GET /v1/config/dlp
現在のDLPホストおよび証明書の構成を結合されたビューとして返します。リクエストボディはありません。
Example request
GET /v1/config/dlp HTTP/1.1 Host: <appliance_ip>:8443
Success response — 200 OK
DLPがまだ設定されていません：
{
"service": "dlp",
"host_config_configured": false,
"certificate_configured": false
}
DLP 完全構成：
{
"service": "dlp",
"host_config_configured": true,
"host_config": {
"host_url": "https://dlp.example.com"
},
"host_config_updated_at": "2026-01-15T00:00:00Z",
"certificate_configured": true,
"certificate": {
"subject": "CN=dlp.example.com,OU=IT,O=Example Inc,L=San Jose,ST=California,C=US",
"issuer": "CN=Example CA,O=Example Inc",
"valid_from": "2026-01-15T00:00:00Z",
"valid_to": "2027-01-15T00:00:00Z",
"serial_number": "175930482619473850261947385026194738502"
},
"certificate_updated_at": "2026-01-15T00:00:00Z"
}
Error response — 409 Conflict
アプライアンスの登録がまだ完了していません：
{
"err_code": "00306",
"message": "invalid resource state: appliance has not finished enrollment yet"
}
Error response — 500 Internal Server Error
予期せぬサーバーエラー：
{
"err_code": "00601",
"message": "System Error"
}
PUT /v1/config/dlp/ca-cert
アプライアンスがDLPアップストリームサービスを信頼するために使用するCA証明書をアップロードします。アップロードされた証明書はCA証明書であり、現在有効である必要があります。
Request body
| 鍵 | タイプ | 例 | デスクリプション |
|---|---|---|---|
certificate | string | "-----BEGIN CERTIFICATE-----..." | 必須。PEMエンコードされたCA証明書またはチェイン（ルート＋中間）（最大32,768文字）。 |
Example request
PUT /v1/config/dlp/ca-cert HTTP/1.1
Host: <appliance_ip>:8443
Content-Type: application/json
{
"certificate": "-----BEGIN CERTIFICATE-----..."
}
Success response — 204 No Content. Empty body.
Error response — 400 Bad Request
証明書が見つかりません:
{
"err_code": "00101",
"message": "invalid format: validation error occurred in the request",
"validation_errors": [
{
"field": "certificate",
"error": "certificate is a required field"
}
]
}
Certificate is not valid PEM/x509:
{
“err_code”: “00101”,
“message”: “invalid format: failed to parse certificate: x509: malformed certificate”
}
Error response — 409 Conflict
アプライアンスの登録がまだ完了していません：
{
"err_code": "00306",
"message": "invalid resource state: appliance has not finished enrollment yet"
}
Error response — 500 Internal Server Error
予期しないサーバーエラー：
{
"err_code": "00601",
"message": "System Error"
}
PUT /v1/config/dlp/hostconfig
DLPアップストリームホストを設定します。このセクションの上部にある接続に関する注記をご覧ください。
Request body
| 鍵 | タイプ | 例 | デスクリプション |
|---|---|---|---|
host_url | string | "https://dlp.example.com" | 必須です。DLPアップストリームベースURL（有効なURL）。 |
Example request
PUT /v1/config/dlp/hostconfig HTTP/1.1
Host: <appliance_ip>:8443
Content-Type: application/json
{
"host_url": "https://dlp.example.com"
}
Success response — 204 No Content. Empty body.
Error response — 400 Bad Request
Invalid host_url:
{
"err_code": "00101",
"message": "invalid format: validation error occurred in the request",
"validation_errors": [
{
"field": "host_url",
"error": "host_url must be a valid URL"
}
]
}
Error response — 409 Conflict
アプライアンスの登録がまだ完了していません：
{
"err_code": "00306",
"message": "invalid resource state: appliance has not finished enrollment yet"
}
Error response — 500 Internal Server Error
Unexpected server error:
{
"err_code": "00601",
"message": "System Error"
}
DELETE /v1/config/dlp/hostconfig
DLPのホスト構成を削除します。リクエストボディはありません。
Example request
DELETE /v1/config/dlp/hostconfig HTTP/1.1 Host: <appliance_ip>:8443
Success response — 204 No Content. Empty body.
Error response — 409 Conflict
アプライアンスの登録がまだ完了していません：
{
"err_code": "00306",
"message": "invalid resource state: appliance has not finished enrollment yet"
}
Error response — 500 Internal Server Error
Unexpected server error:
{
"err_code": "00601",
"message": "System Error"
}
AI Guardrails 設定 API
アプライアンスのAI Guardrailsサービスへの接続を構成します。信頼証明書とアップストリームホストは、別々のエンドポイントを通じて設定されます。DLPとは異なり、ホスト構成ではOAuth/JWT認証フィールドも受け付けます。
409 Conflict を返します。GET /v1/config/ai-guardrails
現在のAI Guardrailsのホストおよび証明書の構成を結合ビューとして返します。リクエストボディはありません。
Example request
GET /v1/config/ai-guardrails HTTP/1.1 Host: <appliance_ip>:8443
Success response — 200 OK
AI Guardrails はまだ構成されていません：
{
"service": "llm",
"host_config_configured": false,
"certificate_configured": false
}
AI Guardrailsの構成が完了しました：
{
"service": "llm",
"host_config_configured": true,
"host_config": {
"host_url": "https://llm.example.com",
"jwt_url": "https://auth.example.com/oauth/token",
"client_id": "aig-client",
"client_secret": "********",
"scope": "aig.read aig.write"
},
"host_config_updated_at": "2026-01-15T00:00:00Z",
"certificate_configured": true,
"certificate": {
"subject": "CN=llm.example.com",
"issuer": "CN=Example CA,O=Example Inc",
"valid_from": "2026-01-15T00:00:00Z",
"valid_to": "2027-01-15T00:00:00Z",
"serial_number": "134817938427490195726719581068945320137"
},
"certificate_updated_at": "2026-01-15T00:00:00Z"
}
Error response — 409 Conflict
アプライアンスの登録がまだ完了していません：
{
"err_code": "00306",
"message": "invalid resource state: appliance has not finished enrollment yet"
}
Error response — 500 Internal Server Error
予期せぬサーバーエラー：
{
"err_code": "00601",
"message": "System Error"
}
PUT /v1/config/ai-guardrails/ca-cert
アプライアンスがAI Guardrailsアップストリームサービスを信頼するために使用するCA証明書をアップロードします。アップロードする証明書はCA証明書であり、現在有効である必要があります。
Request body
| 鍵 | タイプ | 例 | デスクリプション |
|---|---|---|---|
certificate | string | "-----BEGIN CERTIFICATE-----..." | 必須。PEMエンコードされたCA証明書またはチェイン（ルート＋中間）（最大32,768文字）。 |
Example request
PUT /v1/config/ai-guardrails/ca-cert HTTP/1.1
Host: <appliance_ip>:8443
Content-Type: application/json
{
"certificate": "-----BEGIN CERTIFICATE-----..."
}
Success response — 204 No Content. Empty body.
Error response — 400 Bad Request
Missing certificate:
{
"err_code": "00101",
"message": "invalid format: validation error occurred in the request",
"validation_errors": [
{
"field": "certificate",
"error": "certificate is a required field"
}
]
}
Certificate is not valid PEM/x509:
{
"err_code": "00101",
"message": "invalid format: failed to parse certificate: x509: malformed certificate"
}
Error response — 409 Conflict
アプライアンスの登録がまだ完了していません：
{
"err_code": "00306",
"message": "invalid resource state: appliance has not finished enrollment yet"
}
Error response — 500 Internal Server Error
Unexpected server error:
{
"err_code": "00601",
"message": "System Error"
}
PUT /v1/config/ai-guardrails/hostconfig
AI Guardrailsの上流ホストとOAuth/JWT認証を設定します。このセクションの冒頭にある接続に関する注意事項をご覧ください。
Request body
| 鍵 | タイプ | 例 | デスクリプション |
|---|---|---|---|
host_url | string | "https://llm.example.com" | 必須。アップストリームサービスのベースURL（有効なURL）。 |
jwt_url | string | "https://auth.example.com/oauth/token" | Optional. OAuth/JWT token endpoint (valid URL). |
client_id | string | "aig-client" | Optional. OAuth client ID. |
client_secret | string | "s3cr3t" | Optional. OAuth client secret. |
scope | string | "llm.read" | Optional. OAuth scope. |
Example request
PUT /v1/config/ai-guardrails/hostconfig HTTP/1.1
Host: <appliance_ip>:8443
Content-Type: application/json
{
"host_url": "https://llm.example.com",
"jwt_url": "https://auth.example.com/oauth/token",
"client_id": "aig-client",
"client_secret": "YOUR_CLIENT_SECRET",
"scope": "llm.read"
}
Success response — 204 No Content. Empty body.
Error response — 400 Bad Request
Invalid jwt_url:
{
"err_code": "00101",
"message": "invalid format: validation error occurred in the request",
"validation_errors": [
{
"field": "jwt_url",
"error": "jwt_url must be a valid URL"
}
]
}
Error response — 409 Conflict
アプライアンスの登録がまだ完了していません：
{
"err_code": "00306",
"message": "invalid resource state: appliance has not finished enrollment yet"
}
Error response — 500 Internal Server Error
Unexpected server error:
{
"err_code": "00601",
"message": "System Error"
}
DELETE /v1/config/ai-guardrails/hostconfig
AI Guardrailsのホスト構成を削除します。リクエストボディはありません。
Example request
DELETE /v1/config/ai-guardrails/hostconfig HTTP/1.1 Host: <appliance_ip>:8443
Success response — 204 No Content. Empty body.
Error response — 409 Conflict
アプライアンスの登録がまだ完了していません：
{
"err_code": "00306",
"message": "invalid resource state: appliance has not finished enrollment yet"
}
Error response — 500 Internal Server Error
予期せぬサーバーエラー：
{
“err_code”: “00601”,
“message”: “システムエラー”
}