Configuration de l'API - Documentation technique de Netskope

L’API de configuration d’AI Gateway vous permet de configurer une appliance AI Gateway via HTTPS au lieu de la console interactive. Elle couvre l’enregistrement des appliances, la gestion des certificats TLS ainsi que les connexions aux services DLP (Prévention des pertes de données) et AI Guardrails.

Chaque point de terminaison de cette API :

Utilise HTTPS sur le port 8443. L'API ne prend pas en charge le protocole HTTP en clair.
Est ancré à l'adresse /v1/config.
Nécessite un bearer token dans l'en-tête Authorization .

Authentification

L’API est désactivée par défaut. Vous l’activez en vous connectant en connecting to the appliance over SSH tant que nsadmin compte d’opérateur et en enable-api exécutant. L’activation de l’API ouvre le port réseau et émet un jeton d’accès :

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

L'exécution de ssh nsadmin@<appliance_ip> sans commande vous place directement dans la console interactive aig-cli, où vous pouvez taper enable-api --ttl 168h directement.
Le jeton s'affiche once lors de sa génération et ne peut plus être récupéré. Stockez-le en toute sécurité.
La durée de --ttl est une durée positive écrite sous la forme d'un nombre suivi d'un suffixe d'unité — h (heures), m (minutes) ou s (secondes) ; les unités peuvent être combinées, comme dans 1h30m. Il n'y a pas d'unité de jour, utilisez donc 168h pour 7 jours. La valeur par défaut est 24h lorsqu'il est omis.
Un seul jeton est valide à la fois. La réactivation de l'API émet un New jeton et invalide le précédent.

Incluez le jeton dans chaque requête :

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.

Résumé des points de terminaison

Group	Method and Path	Description
Bootstrap	`POST /v1/config/bootstrap`	Démarrer l'inscription automatisée (avec option de configuration DLP (Prévention des pertes de données) / AI Guardrails)
Bootstrap	`GET /v1/config/bootstrap`	Vérifier le statut d’inscription
Certificate	`GET /v1/config/certificate/status`	Obtenir les informations de certificat actuelles
Certificate	`POST /v1/config/certificate/csr`	Générer une demande de signature de certificat
Certificate	`POST /v1/config/certificate/install`	Installer un certificat signé par une autorité de certification
DLP (Prévention des pertes de données)	`GET /v1/config/dlp`	Obtenir la configuration DLP (Prévention des pertes de données) actuelle
DLP (Prévention des pertes de données)	`PUT /v1/config/dlp/ca-cert`	Télécharger le certificat d'autorité de certification pour l'amont DLP (Prévention des pertes de données)
DLP (Prévention des pertes de données)	`PUT /v1/config/dlp/hostconfig`	Définir l'hôte amont DLP (Prévention des pertes de données)
DLP (Prévention des pertes de données)	`DELETE /v1/config/dlp/hostconfig`	Supprimer la configuration de l’hôte DLP (Prévention des pertes de données)
AI Guardrails	`GET /v1/config/ai-guardrails`	Obtenir la configuration actuelle d'AI Guardrails
AI Guardrails	`PUT /v1/config/ai-guardrails/ca-cert`	Téléchargez le certificat CA pour l'amont AI Guardrails
AI Guardrails	`PUT /v1/config/ai-guardrails/hostconfig`	Définir l'hôte amont AI Guardrails et l'authentification OAuth
AI Guardrails	`DELETE /v1/config/ai-guardrails/hostconfig`	Supprimer la configuration de l'hôte AI Guardrails

API de amorçage

Runs automated appliance enrollment, optionally applying DLP (Prévention des pertes de données) and/or AI Guardrails configuration at the same time.

POST /v1/config/bootstrap

Lance l'inscription de l'appliance à l'aide du jeton d'inscription fourni et applique toute configuration DLP ou AI Guardrails incluse.

Request body

Clé	Type	Exemple	Description
`enrollment_token`	string	`"eyJhbGciOi..."`	Requis. Jeton d’enrôlement (2048 caractères max.).
`dlp`	object	`{"host":"https://dlp.example.com","certificate":"-----BEGIN CERTIFICATE-----..."}`	Optionnel. Configuration DLP (Prévention des pertes de données) à appliquer lors de l'enrôlement. Voir l'objet DLP (Prévention des pertes de données) ci-dessous.
`ai_guardrails`	object	`{"host":"https://llm.example.com","jwt_url":"https://auth.example.com/oauth/token"}`	Facultatif. Configuration d’AI Guardrails à appliquer lors de l’inscription. Voir l’ objet AI Guardrails ci-dessous.

dlp object — si l'objet dlp est présent, les deux champs sont obligatoires.

Clé	Type	Exemple	Description
`certificate`	string	`"-----BEGIN CERTIFICATE-----..."`	Obligatoire. Certificat d'autorité de certification encodé au format PEM pour l'hôte amont DLP (Prévention des pertes de données) (5 120 caractères maximum).
`host`	string	`"https://dlp.example.com"`	Requis. URL de base amont DLP (Prévention des pertes de données) (URL valide, 256 caractères max).

ai_guardrails object

Clé	Type	Exemple	Description
`host`	string	`"https://llm.example.com"`	Obligatoire. URL de base en amont d'AI Guardrails (URL valide, 256 caractères max).
`certificate`	string	`"-----BEGIN CERTIFICATE-----..."`	Facultatif. Certificat d'autorité de certification encodé en PEM pour le système amont d'AI Guardrails (max. 5 120 caractères).
`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.

Démarrage du amorçage, aucune configuration facultative demandée :

{
  "status": "running"
}

Amorçage démarré, configuration de la DLP (Prévention des pertes de données) et des AI Guardrails en attente :

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

Error response — 400 Bad Request

Jeton d'inscription manquant :

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

Échec de la persistance du statut d’initialisation :

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

OBTENIR /v1/config/bootstrap

Renvoie le statut d’enrôlement actuel.

Field	Type	Description
`status`	string	Statut global : `not_started`, `running`, `completed` ou `failed`
`dlp`	string	Statut par service : `pending`, `completed`, `failed` ou `skipped`
`ai_guardrails`	string	Statut par service : `pending`, `completed`, `failed` ou `skipped`

Un échec lors de l'application de la configuration optionnelle de DLP (Prévention des pertes de données) ou d'AI Guardrails n'entraîne pas l'échec de l'inscription globale.

Example request

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

Success response — 200 OK

Bootstrap non encore déclenché :

{
  "status": "not_started"
}

Initialisation en cours :

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

Bootstrap completed, no optional config requested:

{
  "status": "completed"
}

Bootstrap terminé, DLP et AI Guardrails configurés :

{
  "status": "completed",
  "dlp": "completed",
  "ai_guardrails": "completed"
}

Bootstrap failed, optional steps auto-skipped:

{
  "status": "failed",
  "dlp": "skipped",
  "ai_guardrails": "skipped"
}

API de certificat

Gérer le certificat TLS de la passerelle de l'appliance. Le déroulement type est le suivant : générer une demande de signature de certificat (CSR), la faire signer par votre autorité de certification (CA), puis installer le certificat signé. Les certificats installés prennent effet sans qu'il soit nécessaire de redémarrer l'appliance.

POST /v1/config/certificate/csr

Génère une demande de signature de certificat pour le certificat de la passerelle.

Request body

Clé	Type	Exemple	Description
`common_name`	string	`"gateway.example.com"`	Requis. CN du certificat (256 caractères max).
`organization`	string	`"Example Inc"`	Optionnel. Nom de l’organisation (O) (256 caractères max.).
`organization_unit`	string	`"IT"`	Optional. Organizational Unit (OU) (max 256 chars).
`email`	string	`"admin@example.com"`	Facultatif. Adresse e-mail pour l'objet (format d'e-mail valide).
`country`	string	`"US"`	Facultatif. Code pays à deux lettres (C), exactement 2 caractères alphabétiques.
`state`	string	`"California"`	Optional. State or Province (ST) (max 256 chars).
`city`	string	`"San Jose"`	Facultatif. Ville ou localité (L) (256 caractères max).
`key_algorithm`	string	`"ecdsa"`	Facultatif. Algorithme de clé privée ; l’un des éléments suivants : `ecdsa`, `rsa`, `ed25519`. La valeur par défaut est `ecdsa` (P-256) lorsqu’elle n’est pas définie.
`key_size`	integer	`2048`	Optionnel. Taille de la clé RSA en bits ; une valeur parmi `2048`, `3072`, `4096`. S'applique lorsque `key_algorithm` est `rsa`.
`key_curve`	string	`"P256"`	Facultatif. Courbe ECDSA ; l’une de `P256`, `P384`, `P521`. S’applique lorsque `key_algorithm` est `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

common_name manquant :

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

Erreur de serveur inattendue :

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

POST /v1/config/certificate/install

Installe un certificat signé par l'autorité de certification (CA) pour la passerelle. Le certificat doit correspondre à la paire de clés générée pour la demande de signature de certificat (CSR) la plus récente. Le nouveau certificat prend effet immédiatement, sans redémarrage.

Request body

Clé	Type	Exemple	Description
`certificate`	string	`"-----BEGIN CERTIFICATE-----..."`	Obligatoire. Certificat X.509 encodé au format PEM (6500 caractères max.).

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

Le certificat dépasse la longueur maximale :

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

Inadéquation entre le certificat et la clé :

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

Error response — 404 Not Found

Aucune clé privée sur l’appliance (par ex. générez d’abord une demande de signature de certificat [CSR] :) -> générez d’abord un CSR) :

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

Error response — 500 Internal Server Error

Erreur de serveur inattendue :

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

GET /v1/config/certificate/status

Renvoie les métadonnées actuelles du certificat de la passerelle. Aucun corps de requête.

Example request

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

Success response — 200 OK

Certificat actif :

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

Aucun certificat installé :

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

Error response — 500 Internal Server Error

Erreur de serveur inattendue :

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

API de configuration DLP (Prévention des pertes de données)

Configures the appliance’s connection to the DLP (Prévention des pertes de données) service. The trust certificate and the upstream host are set through separate endpoints. The DLP (Prévention des pertes de données) host configuration accepts only a host URL (no OAuth fields).

GET /v1/config/dlp

Renvoie la configuration actuelle de l'hôte DLP et du certificat sous forme de vue combinée. Aucun corps de requête.

Example request

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

Success response — 200 OK

DLP (Prévention des pertes de données) not configured yet:

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

DLP (Prévention des pertes de données) entièrement configuré :

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

L'enregistrement de l'appliance n'est pas encore terminé :

{
  "err_code": "00306",
  "message": "invalid resource state: appliance has not finished enrollment yet"
}

Error response — 500 Internal Server Error

Erreur de serveur inattendue :

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

PUT /v1/config/dlp/ca-cert

Uploads the CA certificate the appliance uses to trust the DLP (Prévention des pertes de données) upstream service. The uploaded certificate must be a CA certificate and currently valid.

Request body

Clé	Type	Exemple	Description
`certificate`	string	`"-----BEGIN CERTIFICATE-----..."`	Requis. Certificat CA ou chaîne encodé(e) en PEM (racine + intermédiaires) (max 32 768 caractères).

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

Certificat manquant :

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

L'appliance n'a pas encore terminé son enregistrement :

{
  "err_code": "00306",
  "message": "invalid resource state: appliance has not finished enrollment yet"
}

Error response — 500 Internal Server Error

erreur de serveur inattendue :

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

PUT /v1/config/DLP (Prévention des pertes de données)/hostconfig

Définit l'hôte en amont DLP (Prévention des pertes de données). Consultez la note de connectivité en haut de cette section.

Request body

Clé	Type	Exemple	Description
`host_url`	string	`"https://dlp.example.com"`	Requis. URL de base amont DLP (Prévention des pertes de données) (URL valide).

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

L'appliance n'a pas encore terminé son enregistrement :

{
  "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 (Prévention des pertes de données)/hostconfig

Supprime la configuration de l'hôte DLP (Prévention des pertes de données). Aucun corps de requête.

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

L'appliance n'a pas encore terminé son enregistrement :

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

API de configuration AI Guardrails

Configure la connexion de l'appareil au service AI Guardrails. Le certificat de confiance et l'hôte en amont sont définis par le biais de points de terminaison distincts. Contrairement au DLP (Prévention des pertes de données), la configuration de l'hôte accepte également les champs d'authentification OAuth/JWT.

Configurez AI Guardrails uniquement une fois l’enregistrement de l’appareil terminé. D’ici là, ces points de terminaison renvoient 409 Conflict.

GET /v1/config/ai-guardrails

Renvoie la configuration actuelle de l'hôte et du certificat AI Guardrails sous forme de vue combinée. Aucun corps de requête.

Example request

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

Success response — 200 OK

AI Guardrails non encore configuré :

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

AI Guardrails entièrement configurées :

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

L'appliance n'a pas encore terminé son enregistrement :

{
  "err_code": "00306",
  "message": "invalid resource state: appliance has not finished enrollment yet"
}

Error response — 500 Internal Server Error

Erreur de serveur inattendue :

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

PUT /v1/config/ai-guardrails/ca-cert

Télécharge le certificat d’autorité de certification (CA) que l’appareil utilise pour approuver le service en amont d’AI Guardrails. Le certificat téléchargé doit être un certificat d’autorité de certification (CA) et être actuellement valide.

Request body

Clé	Type	Exemple	Description
`certificate`	string	`"-----BEGIN CERTIFICATE-----..."`	Requis. Certificat CA ou chaîne encodé(e) en PEM (racine + intermédiaires) (max 32 768 caractères).

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

L'appliance n'a pas encore terminé son enregistrement :

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

Définit l’hôte en amont et l’authentification OAuth/JWT d’AI Guardrails. Consultez la note sur la connectivité en haut de cette section.

Request body

Clé	Type	Exemple	Description
`host_url`	string	`"https://llm.example.com"`	Obligatoire. URL de base du service amont (URL valide).
`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

L'appliance n'a pas encore terminé son enregistrement :

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

Supprime la configuration de l'hôte AI Guardrails. Aucun corps de requête.

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

L'appliance n'a pas encore terminé son enregistrement :

{
  "err_code": "00306",
  "message": "invalid resource state: appliance has not finished enrollment yet"
}

Error response — 500 Internal Server Error

Erreur de serveur inattendue :

{
“err_code”: “00601”,
“message”: “System Error”
}