Configuration API - Netskope Technical Documentation

The AI Gateway configuration API lets you configure an AI Gateway appliance over HTTPS instead of the interactive console. It covers appliance enrollment, TLS certificate management, and the DLP and AI Guardrails service connections.

Every endpoint in this API:

Uses HTTPS on port 8443. The API does not support plain HTTP.
Is rooted at /v1/config.
Requires a bearer token in the Authorization header.

Authentication

The API is disabled by default. You enable it by connecting to the appliance over SSH as the nsadmin operator account and running enable-api. Enabling the API opens the network port and issues an access token:

# 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'

Running ssh nsadmin@<appliance_ip> with no command instead drops you into the interactive aig-cli console, where you can type enable-api --ttl 168h directly.
The token is shown once at generation time and cannot be retrieved again. Store it securely.
The --ttl lifetime is a positive duration written as a number followed by a unit suffix — h (hours), m (minutes) or s (seconds); units may be combined, as in 1h30m. There is no day unit, so use 168h for 7 days. It defaults to 24h when omitted.
Only one token is valid at a time. Enabling the API again issues a new token and invalidates the previous one.

Include the token on every request:

Authorization: Bearer <token>

If your request has a missing, malformed, invalid, or expired token, the API returns 401 Unauthorized. When a token expires, the port stays open until you run disable-api. The API simply returns 401 until you generate a new token.

Endpoint Summary

Group	Method and Path	Description
Bootstrap	`POST /v1/config/bootstrap`	Start automated enrollment (optionally with DLP / AI Guardrails config)
Bootstrap	`GET /v1/config/bootstrap`	Check enrollment status
Certificate	`GET /v1/config/certificate/status`	Get current certificate information
Certificate	`POST /v1/config/certificate/csr`	Generate a Certificate Signing Request
Certificate	`POST /v1/config/certificate/install`	Install a CA-signed certificate
DLP	`GET /v1/config/dlp`	Get current DLP configuration
DLP	`PUT /v1/config/dlp/ca-cert`	Upload the CA certificate for the DLP upstream
DLP	`PUT /v1/config/dlp/hostconfig`	Set the DLP upstream host
DLP	`DELETE /v1/config/dlp/hostconfig`	Remove the DLP host configuration
AI Guardrails	`GET /v1/config/ai-guardrails`	Get current AI Guardrails configuration
AI Guardrails	`PUT /v1/config/ai-guardrails/ca-cert`	Upload the CA certificate for the AI Guardrails upstream
AI Guardrails	`PUT /v1/config/ai-guardrails/hostconfig`	Set the AI Guardrails upstream host and OAuth authentication
AI Guardrails	`DELETE /v1/config/ai-guardrails/hostconfig`	Remove the AI Guardrails host configuration

Bootstrap API

Runs automated appliance enrollment, optionally applying DLP and/or AI Guardrails configuration at the same time.

POST /v1/config/bootstrap

Starts appliance enrollment using the enrollment token you provide, and applies any DLP or AI Guardrails configuration you include.

Request body

Key	Type	Example	Description
`enrollment_token`	string	`"eyJhbGciOi..."`	Required. Enrollment token (max 2048 chars).
`dlp`	object	`{"host":"https://dlp.example.com","certificate":"-----BEGIN CERTIFICATE-----..."}`	Optional. DLP configuration to apply during enrollment. See DLP object below.
`ai_guardrails`	object	`{"host":"https://llm.example.com","jwt_url":"https://auth.example.com/oauth/token"}`	Optional. AI Guardrails configuration to apply during enrollment. See AI Guardrails object below.

dlp object — if the dlp object is present, both fields are required.

Key	Type	Example	Description
`certificate`	string	`"-----BEGIN CERTIFICATE-----..."`	Required. PEM-encoded CA certificate for the DLP upstream (max 5120 chars).
`host`	string	`"https://dlp.example.com"`	Required. DLP upstream base URL (valid URL, max 256 chars).

ai_guardrails object

Key	Type	Example	Description
`host`	string	`"https://llm.example.com"`	Required. AI Guardrails upstream base URL (valid URL, max 256 chars).
`certificate`	string	`"-----BEGIN CERTIFICATE-----..."`	Optional. PEM-encoded CA certificate for the AI Guardrails upstream (max 5120 chars).
`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.

Bootstrap started, no optional config requested:

{
  "status": "running"
}

Bootstrap started, DLP and AI Guardrails config pending:

{
  "status": "running",
  "dlp": "pending",
  "ai_guardrails": "pending"
}

Error response — 400 Bad Request

Missing 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

Failed to persist bootstrap status:

{
  "err_code": "00601",
  "message": "System Error"
}

GET /v1/config/bootstrap

Returns the current enrollment status.

Field	Type	Description
`status`	string	Overall status: `not_started`, `running`, `completed`, or `failed`
`dlp`	string	Per-service status: `pending`, `completed`, `failed`, or `skipped`
`ai_guardrails`	string	Per-service status: `pending`, `completed`, `failed`, or `skipped`

A failure applying the optional DLP or AI Guardrails configuration does not fail the overall enrollment.

Example request

GET /v1/config/bootstrap HTTP/1.1
Host: <appliance_ip>:8443

Success response — 200 OK

Bootstrap not yet triggered:

{
  "status": "not_started"
}

Bootstrap in progress:

{
  "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"
}

Certificate API

Manage the appliance’s gateway TLS certificate. The typical flow is: generate a CSR, have it signed by your CA, then install the signed certificate. Installed certificates take effect without an appliance restart.

POST /v1/config/certificate/csr

Generates a Certificate Signing Request for the gateway certificate.

Request body

Key	Type	Example	Description
`common_name`	string	`"gateway.example.com"`	Required. Certificate CN (max 256 chars).
`organization`	string	`"Example Inc"`	Optional. Organization name (O) (max 256 chars).
`organization_unit`	string	`"IT"`	Optional. Organizational Unit (OU) (max 256 chars).
`email`	string	`"admin@example.com"`	Optional. Email address for the subject (valid email format).
`country`	string	`"US"`	Optional. Two-letter country code (C), exactly 2 alpha chars.
`state`	string	`"California"`	Optional. State or Province (ST) (max 256 chars).
`city`	string	`"San Jose"`	Optional. City or Locality (L) (max 256 chars).
`key_algorithm`	string	`"ecdsa"`	Optional. Private-key algorithm; one of `ecdsa`, `rsa`, `ed25519`. Defaults to `ecdsa` (P-256) when unset.
`key_size`	integer	`2048`	Optional. RSA key size in bits; one of `2048`, `3072`, `4096`. Applies when `key_algorithm` is `rsa`.
`key_curve`	string	`"P256"`	Optional. ECDSA curve; one of `P256`, `P384`, `P521`. Applies when `key_algorithm` is `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 generated:

{
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----\n"
}

Error response — 400 Bad Request

Missing common_name:

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

Unexpected server error:

{
  "err_code": "00601",
  "message": "System Error"
}

POST /v1/config/certificate/install

Installs a CA-signed certificate for the gateway. The certificate must match the key pair generated for the most recent CSR. The new certificate takes effect immediately, without a restart.

Request body

Key	Type	Example	Description
`certificate`	string	`"-----BEGIN CERTIFICATE-----..."`	Required. PEM-encoded X.509 certificate (max 6500 chars).

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

Certificate exceeds max length:

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

Certificate/key mismatch:

{
  "err_code": "00502",
  "message": "forbidden: failed to install certificate"
}

Error response — 404 Not Found

No private key on appliance (e.g. generate a CSR first):

{
  "err_code": "00301",
  "message": "resource not found: failed to install certificate"
}

Error response — 500 Internal Server Error

Unexpected server error:

{
  "err_code": "00601",
  "message": "System Error"
}

GET /v1/config/certificate/status

Returns the current gateway certificate metadata. No request body.

Example request

GET /v1/config/certificate/status HTTP/1.1
Host: <appliance_ip>:8443

Success response — 200 OK

Active certificate:

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

No certificate installed:

{
  "err_code": "00301",
  "message": "resource not found: failed to get certificate status"
}

Error response — 500 Internal Server Error

Unexpected server error:

{
  "err_code": "00601",
  "message": "System Error"
}

DLP Configuration API

Configures the appliance’s connection to the DLP service. The trust certificate and the upstream host are set through separate endpoints. The DLP host configuration accepts only a host URL (no OAuth fields).

GET /v1/config/dlp

Returns the current DLP host and certificate configuration as a combined view. No request body.

Example request

GET /v1/config/dlp HTTP/1.1
Host: <appliance_ip>:8443

Success response — 200 OK

DLP not configured yet:

{
  "service": "dlp",
  "host_config_configured": false,
  "certificate_configured": false
}

DLP fully configured:

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

Appliance has not finished enrollment yet:

{
  "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/dlp/ca-cert

Uploads the CA certificate the appliance uses to trust the DLP upstream service. The uploaded certificate must be a CA certificate and currently valid.

Request body

Key	Type	Example	Description
`certificate`	string	`"-----BEGIN CERTIFICATE-----..."`	Required. PEM-encoded CA certificate or chain (root + intermediates) (max 32768 chars).

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

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

Appliance has not finished enrollment yet:

{
  "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/dlp/hostconfig

Sets the DLP upstream host. See the connectivity note at the top of this section.

Request body

Key	Type	Example	Description
`host_url`	string	`"https://dlp.example.com"`	Required. DLP upstream base URL (valid 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

Appliance has not finished enrollment yet:

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

Removes the DLP host configuration. No request body.

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

Appliance has not finished enrollment yet:

{
  "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 Configuration API

Configures the appliance’s connection to the AI Guardrails service. The trust certificate and the upstream host are set through separate endpoints. Unlike DLP, the host configuration also accepts OAuth/JWT authentication fields.

Configure AI Guardrails only after the appliance finishes enrollment. Until then, these endpoints return 409 Conflict.

GET /v1/config/ai-guardrails

Returns the current AI Guardrails host and certificate configuration as a combined view. No request body.

Example request

GET /v1/config/ai-guardrails HTTP/1.1
Host: <appliance_ip>:8443

Success response — 200 OK

AI Guardrails not configured yet:

{
  "service": "llm",
  "host_config_configured": false,
  "certificate_configured": false
}

AI Guardrails fully configured:

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

Appliance has not finished enrollment yet:

{
  "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/ca-cert

Uploads the CA certificate the appliance uses to trust the AI Guardrails upstream service. The uploaded certificate must be a CA certificate and currently valid.

Request body

Key	Type	Example	Description
`certificate`	string	`"-----BEGIN CERTIFICATE-----..."`	Required. PEM-encoded CA certificate or chain (root + intermediates) (max 32768 chars).

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

Appliance has not finished enrollment yet:

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

Sets the AI Guardrails upstream host and OAuth/JWT authentication. See the connectivity note at the top of this section.

Request body

Key	Type	Example	Description
`host_url`	string	`"https://llm.example.com"`	Required. Upstream service base URL (valid 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

Appliance has not finished enrollment yet:

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

Removes the AI Guardrails host configuration. No request body.

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

Appliance has not finished enrollment yet:

{
  "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”
}

Every endpoint in this API:

Uses HTTPS on port 8443. The API does not support plain HTTP.
Is rooted at /v1/config.
Requires a bearer token in the Authorization header.

Authentication

# 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'

Running ssh nsadmin@<appliance_ip> with no command instead drops you into the interactive aig-cli console, where you can type enable-api --ttl 168h directly.
The token is shown once at generation time and cannot be retrieved again. Store it securely.
The --ttl lifetime is a positive duration written as a number followed by a unit suffix — h (hours), m (minutes) or s (seconds); units may be combined, as in 1h30m. There is no day unit, so use 168h for 7 days. It defaults to 24h when omitted.
Only one token is valid at a time. Enabling the API again issues a new token and invalidates the previous one.

Include the token on every request:

Authorization: Bearer <token>

Endpoint Summary

Group	Method and Path	Description
Bootstrap	`POST /v1/config/bootstrap`	Start automated enrollment (optionally with DLP / AI Guardrails config)
Bootstrap	`GET /v1/config/bootstrap`	Check enrollment status
Certificate	`GET /v1/config/certificate/status`	Get current certificate information
Certificate	`POST /v1/config/certificate/csr`	Generate a Certificate Signing Request
Certificate	`POST /v1/config/certificate/install`	Install a CA-signed certificate
DLP	`GET /v1/config/dlp`	Get current DLP configuration
DLP	`PUT /v1/config/dlp/ca-cert`	Upload the CA certificate for the DLP upstream
DLP	`PUT /v1/config/dlp/hostconfig`	Set the DLP upstream host
DLP	`DELETE /v1/config/dlp/hostconfig`	Remove the DLP host configuration
AI Guardrails	`GET /v1/config/ai-guardrails`	Get current AI Guardrails configuration
AI Guardrails	`PUT /v1/config/ai-guardrails/ca-cert`	Upload the CA certificate for the AI Guardrails upstream
AI Guardrails	`PUT /v1/config/ai-guardrails/hostconfig`	Set the AI Guardrails upstream host and OAuth authentication
AI Guardrails	`DELETE /v1/config/ai-guardrails/hostconfig`	Remove the AI Guardrails host configuration

Bootstrap API

Runs automated appliance enrollment, optionally applying DLP and/or AI Guardrails configuration at the same time.

POST /v1/config/bootstrap

Starts appliance enrollment using the enrollment token you provide, and applies any DLP or AI Guardrails configuration you include.

Request body

Key	Type	Example	Description
`enrollment_token`	string	`"eyJhbGciOi..."`	Required. Enrollment token (max 2048 chars).
`dlp`	object	`{"host":"https://dlp.example.com","certificate":"-----BEGIN CERTIFICATE-----..."}`	Optional. DLP configuration to apply during enrollment. See DLP object below.
`ai_guardrails`	object	`{"host":"https://llm.example.com","jwt_url":"https://auth.example.com/oauth/token"}`	Optional. AI Guardrails configuration to apply during enrollment. See AI Guardrails object below.

dlp object — if the dlp object is present, both fields are required.

Key	Type	Example	Description
`certificate`	string	`"-----BEGIN CERTIFICATE-----..."`	Required. PEM-encoded CA certificate for the DLP upstream (max 5120 chars).
`host`	string	`"https://dlp.example.com"`	Required. DLP upstream base URL (valid URL, max 256 chars).

ai_guardrails object

Key	Type	Example	Description
`host`	string	`"https://llm.example.com"`	Required. AI Guardrails upstream base URL (valid URL, max 256 chars).
`certificate`	string	`"-----BEGIN CERTIFICATE-----..."`	Optional. PEM-encoded CA certificate for the AI Guardrails upstream (max 5120 chars).
`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.

Bootstrap started, no optional config requested:

{
  "status": "running"
}

Bootstrap started, DLP and AI Guardrails config pending:

{
  "status": "running",
  "dlp": "pending",
  "ai_guardrails": "pending"
}

Error response — 400 Bad Request

Missing 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

Failed to persist bootstrap status:

{
  "err_code": "00601",
  "message": "System Error"
}

GET /v1/config/bootstrap

Returns the current enrollment status.

Field	Type	Description
`status`	string	Overall status: `not_started`, `running`, `completed`, or `failed`
`dlp`	string	Per-service status: `pending`, `completed`, `failed`, or `skipped`
`ai_guardrails`	string	Per-service status: `pending`, `completed`, `failed`, or `skipped`

A failure applying the optional DLP or AI Guardrails configuration does not fail the overall enrollment.

Example request

GET /v1/config/bootstrap HTTP/1.1
Host: <appliance_ip>:8443

Success response — 200 OK

Bootstrap not yet triggered:

{
  "status": "not_started"
}

Bootstrap in progress:

{
  "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"
}

Certificate API

POST /v1/config/certificate/csr

Generates a Certificate Signing Request for the gateway certificate.

Request body

Key	Type	Example	Description
`common_name`	string	`"gateway.example.com"`	Required. Certificate CN (max 256 chars).
`organization`	string	`"Example Inc"`	Optional. Organization name (O) (max 256 chars).
`organization_unit`	string	`"IT"`	Optional. Organizational Unit (OU) (max 256 chars).
`email`	string	`"admin@example.com"`	Optional. Email address for the subject (valid email format).
`country`	string	`"US"`	Optional. Two-letter country code (C), exactly 2 alpha chars.
`state`	string	`"California"`	Optional. State or Province (ST) (max 256 chars).
`city`	string	`"San Jose"`	Optional. City or Locality (L) (max 256 chars).
`key_algorithm`	string	`"ecdsa"`	Optional. Private-key algorithm; one of `ecdsa`, `rsa`, `ed25519`. Defaults to `ecdsa` (P-256) when unset.
`key_size`	integer	`2048`	Optional. RSA key size in bits; one of `2048`, `3072`, `4096`. Applies when `key_algorithm` is `rsa`.
`key_curve`	string	`"P256"`	Optional. ECDSA curve; one of `P256`, `P384`, `P521`. Applies when `key_algorithm` is `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 generated:

{
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----\n"
}

Error response — 400 Bad Request

Missing common_name:

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

Unexpected server error:

{
  "err_code": "00601",
  "message": "System Error"
}

POST /v1/config/certificate/install

Installs a CA-signed certificate for the gateway. The certificate must match the key pair generated for the most recent CSR. The new certificate takes effect immediately, without a restart.

Request body

Key	Type	Example	Description
`certificate`	string	`"-----BEGIN CERTIFICATE-----..."`	Required. PEM-encoded X.509 certificate (max 6500 chars).

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

Certificate exceeds max length:

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

Certificate/key mismatch:

{
  "err_code": "00502",
  "message": "forbidden: failed to install certificate"
}

Error response — 404 Not Found

No private key on appliance (e.g. generate a CSR first):

{
  "err_code": "00301",
  "message": "resource not found: failed to install certificate"
}

Error response — 500 Internal Server Error

Unexpected server error:

{
  "err_code": "00601",
  "message": "System Error"
}

GET /v1/config/certificate/status

Returns the current gateway certificate metadata. No request body.

Example request

GET /v1/config/certificate/status HTTP/1.1
Host: <appliance_ip>:8443

Success response — 200 OK

Active certificate:

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

No certificate installed:

{
  "err_code": "00301",
  "message": "resource not found: failed to get certificate status"
}

Error response — 500 Internal Server Error

Unexpected server error:

{
  "err_code": "00601",
  "message": "System Error"
}

DLP Configuration API

GET /v1/config/dlp

Returns the current DLP host and certificate configuration as a combined view. No request body.

Example request

GET /v1/config/dlp HTTP/1.1
Host: <appliance_ip>:8443

Success response — 200 OK

DLP not configured yet:

{
  "service": "dlp",
  "host_config_configured": false,
  "certificate_configured": false
}

DLP fully configured:

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

Appliance has not finished enrollment yet:

{
  "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/dlp/ca-cert

Uploads the CA certificate the appliance uses to trust the DLP upstream service. The uploaded certificate must be a CA certificate and currently valid.

Request body

Key	Type	Example	Description
`certificate`	string	`"-----BEGIN CERTIFICATE-----..."`	Required. PEM-encoded CA certificate or chain (root + intermediates) (max 32768 chars).

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

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

Appliance has not finished enrollment yet:

{
  "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/dlp/hostconfig

Sets the DLP upstream host. See the connectivity note at the top of this section.

Request body

Key	Type	Example	Description
`host_url`	string	`"https://dlp.example.com"`	Required. DLP upstream base URL (valid 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

Appliance has not finished enrollment yet:

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

Removes the DLP host configuration. No request body.

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

Appliance has not finished enrollment yet:

{
  "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 Configuration API

Configure AI Guardrails only after the appliance finishes enrollment. Until then, these endpoints return 409 Conflict.

GET /v1/config/ai-guardrails

Returns the current AI Guardrails host and certificate configuration as a combined view. No request body.

Example request

GET /v1/config/ai-guardrails HTTP/1.1
Host: <appliance_ip>:8443

Success response — 200 OK

AI Guardrails not configured yet:

{
  "service": "llm",
  "host_config_configured": false,
  "certificate_configured": false
}

AI Guardrails fully configured:

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

Appliance has not finished enrollment yet:

{
  "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/ca-cert

Uploads the CA certificate the appliance uses to trust the AI Guardrails upstream service. The uploaded certificate must be a CA certificate and currently valid.

Request body

Key	Type	Example	Description
`certificate`	string	`"-----BEGIN CERTIFICATE-----..."`	Required. PEM-encoded CA certificate or chain (root + intermediates) (max 32768 chars).

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

Appliance has not finished enrollment yet:

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

Sets the AI Guardrails upstream host and OAuth/JWT authentication. See the connectivity note at the top of this section.

Request body

Key	Type	Example	Description
`host_url`	string	`"https://llm.example.com"`	Required. Upstream service base URL (valid 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

Appliance has not finished enrollment yet:

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

Removes the AI Guardrails host configuration. No request body.

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

Appliance has not finished enrollment yet:

{
  "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”
}