Configuration API

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.

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