End-to-End Example: Create / Deploy / Update / Delete a Connector

This guide shows a complete, real-world workflow to manage a connector using SSW APIs: create it, get the command that deploys it on your host, change its settings, and delete it.

What You Will Do

1. Authenticate API key → get sdp_token
2. Pick an edge and a network → get edge_id and the network name
3. Create a connector (or look up an existing one) → get site_id
4. Get the deploy command for Docker / Helm / Linux / Windows / macOS
5. Update the connector settings
6. Clean up by deleting the connector

Auth requirement
All /ztna/v1/... API calls require:

Authorization: Bearer <sdp_token>

💡 Tip
In the API, a connector is called a site. site_id is the connector ID.

Prerequisites

Required

API key that can obtain an SDP token. The user who owns the key needs these roles:

To run every step in this guide, use a key owned by an Admin or Super Admin.

SSW base URL, for example:

https://<your-ssw-host>

A free connector seat in your license. Creating a connector fails once the license limit is reached.

Tools

• curl
• jq (recommended)

Step 1: Get sdp_token

Request

SSW_HOST="<your-ssw-host>"
APIKEY="YOUR_API_KEY"

curl -s -X POST "https://${SSW_HOST}/iam/v1/apikey/authenticate" \
  -H "Content-Type: application/json" \
  -d "{\"apikey\":\"${APIKEY}\"}" \
  -o sdp_iam_token.json

Extract Token

SDP_TOKEN="$(jq -r '.data.sdp_token' sdp_iam_token.json)"
echo "$SDP_TOKEN"

Step 2: Pick an Edge and a Network

Pick an Edge

Each connector connects to one edge. Pick the edge closest to the network the connector will serve.

curl -s -X GET "https://${SSW_HOST}/ztna/v1/edge?connector_support=true&show_position=connector&page_size=10000" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${SDP_TOKEN}" \
  -o edges.json

jq '.data.list[] | {edge_id, name, location}' edges.json

Example output:

{ "edge_id": "8fdfcf14-...", "name": "San Francisco, California", "location": "US" }
{ "edge_id": "5ec20361-...", "name": "Singapore, Singapore", "location": "SG" }

Choose one and save its edge_id:

EDGE_NAME="San Francisco, California"
EDGE_ID="$(jq -r --arg n "$EDGE_NAME" '.data.list[] | select(.name == $n) | .edge_id' edges.json)"
echo "EDGE_ID=$EDGE_ID"

⚠️ Important
The edge cannot be changed after the connector is created. To move a connector to another edge, delete it and create a new one.

Pick a Network

Every connector belongs to a network. Network names differ between organizations, so look yours up instead of assuming a name.

curl -s -X GET "https://${SSW_HOST}/ztna/v1/network?workspace_type=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${SDP_TOKEN}" \
  -o networks.json

jq '.data.list[] | {network_id, name}' networks.json

NETWORK_NAME="$(jq -r '.data.list[0].name' networks.json)"   # or pick one by name
echo "NETWORK_NAME=$NETWORK_NAME"

Step 3: Create a Connector

Request Body

Create Request

CONNECTOR_NAME="dev-qa-api-connector"

curl -s -X POST "https://${SSW_HOST}/ztna/v1/site" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${SDP_TOKEN}" \
  -H "Content-Type: application/json" \
  --data "{
    \"name\": \"${CONNECTOR_NAME}\",
    \"display_name\": \"${CONNECTOR_NAME}\",
    \"edge_id\": \"${EDGE_ID}\",
    \"network_name\": \"${NETWORK_NAME}\",
    \"allow_remote_control\": true,
    \"conn_category\": 0,
    \"cluster_mode\": false,
    \"auto_bandwidth_detection\": false,
    \"enable_shell\": false,
    \"is_scan\": false,
    \"scan_interval\": 20
  }" \
  -o create_result.json

Validate Create Result

CREATE_CODE="$(jq -r '.code' create_result.json)"
if [ "$CREATE_CODE" != "0" ]; then
  echo "Create failed:"
  jq '{code, message}' create_result.json
  exit 1
fi

Extract site_id

SITE_ID="$(jq -r '.data.site_id' create_result.json)"
echo "SITE_ID=$SITE_ID"

Alternative: Look Up an Existing Connector

If the connector already exists, find its site_id by name:

curl -s -X GET "https://${SSW_HOST}/ztna/v1/site/all?workspace_type=0&conn_category=0" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${SDP_TOKEN}" \
  -o connectors.json

SITE_ID="$(jq -r --arg n "$CONNECTOR_NAME" '.data.list[] | select(.name == $n) | .site_id' connectors.json)"
echo "SITE_ID=$SITE_ID"

Step 4: Get the Deploy Command

This returns ready-to-run commands that install the connector and register it with SSW. Run one of them on the host where the connector should run.

Deploy Command Request

curl -s -X GET "https://${SSW_HOST}/ztna/v1/connectorToken/${SITE_ID}/organization?type=All" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${SDP_TOKEN}" \
  -o deploy.json

Response

{
  "code": 0,
  "data": {
    "name": "<deployment_name>",
    "token": "<deploy_token>",
    "all_token": {
      "docker": "docker pull ... && docker run ...",
      "helm": "helm repo add ... && helm install ...",
      "linux": "export SSW_CONNECTOR=... ",
      "desktop": "<deploy_token>",
      "darwin": "bash -c 'export SSW_CONNECTOR=... '",
      "windows": "$env:SSW_CONNECTOR_TOKEN=\"...\" ..."
    },
    "cli": {
      "linux": "bash -c 'arch=$(uname -m) && ... '",
      "darwin": "bash -c 'arch=$(uname -m) && ... '",
      "windows": "$CONNECTOR_DOWNLOAD_URL=\"...\" ..."
    }
  },
  "message": "Success"
}

Extract a Command (Example: Docker)

DEPLOY_CMD="$(jq -r '.data.all_token.docker' deploy.json)"
echo "$DEPLOY_CMD"

⚠️ Important

• The deploy token expires after 24 hours. If you deploy later, call this API again to get a fresh command. This does not affect a connector that is already running.
• The command contains a credential. Treat it like a secret and do not commit it to source control or share it in logs.
• Do not call this API for the same connector in parallel. Concurrent calls are rejected with "Do not generate token so frequently".

Step 5: Update the Connector

The update API replaces the connector settings with the request body. It is not a partial update.

⚠️ Important
Sending only {"display_name": "new-name"} also sets allow_remote_control to false, turns off scanning, clears scan_targets / scan_ports, and sets scan_interval to 0.
Always read the current settings first, change what you need, and send the whole object back.

What Can Be Changed

Read the Current Settings

curl -s -X GET "https://${SSW_HOST}/ztna/v1/site/${SITE_ID}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${SDP_TOKEN}" \
  -o connector.json

jq '.data | {name, display_name, network_id, allow_remote_control, enable_shell, is_scan, scan_targets, scan_ports, scan_interval, supported_functions_config}' connector.json

Build the Update Body

Copy the current settings, then change what you need. This example renames the connector and turns on shell access:

jq '.data | {
      name,
      display_name,
      network_id,
      allow_remote_control,
      auto_bandwidth_detection,
      enable_shell,
      cluster_mode,
      is_scan,
      scan_interval,
      scan_targets,
      scan_ports,
      supported_functions: .supported_functions_config
    }
    | .display_name = "dev-qa-api-connector-renamed"
    | .enable_shell = true' \
  connector.json > update_body.json

cat update_body.json

Send the Update

curl -s -X PUT "https://${SSW_HOST}/ztna/v1/site/${SITE_ID}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${SDP_TOKEN}" \
  -H "Content-Type: application/json" \
  --data @update_body.json \
  -o update_result.json

jq '{code, message}' update_result.json

Read the current settings again to confirm the change.

Step 6: Cleanup — Delete the Connector

⚠️ Important
Deleting a connector also deletes every application that uses it. List them before you delete.

List Applications Using the Connector

curl -s -X GET "https://${SSW_HOST}/ztna/v1/site/${SITE_ID}/app" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${SDP_TOKEN}" | jq .data

Delete Request

curl -s -X DELETE "https://${SSW_HOST}/ztna/v1/site/${SITE_ID}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${SDP_TOKEN}" \
  -o delete_result.json

jq '{code, message}' delete_result.json

Verify Deletion

After deletion, reading the connector returns 40001 Record not found:

curl -s -X GET "https://${SSW_HOST}/ztna/v1/site/${SITE_ID}" \
  -H "Authorization: Bearer ${SDP_TOKEN}" | jq '{code, message}'

{ "code": 40001, "message": "Record not found" }

Common Pitfalls

• ❌ Using the API key directly to call /ztna/v1/... APIs
  → Always use sdp_token
• ❌ Checking only the HTTP status
  → Business errors come back as HTTP 200 with a non-zero code (for example 40001 Record not found). Always check .code; 0 means success.
• ❌ Getting a permission error on Step 4 with a Network Manager key
  → Getting the deploy command requires an Admin or Super Admin key
• ❌ Sending only the changed fields to the update API
  → Omitted fields are reset, including allow_remote_control. Always read first and send the full object.
• ❌ Hard-coding a network name such as Default
  → Network names differ per organization. Look them up in Step 2.
• ❌ Running a deploy command that is more than 24 hours old
  → Call Step 4 again for a fresh command
• ❌ Reusing a connector name
  → Names must be unique within the organization, including connectors created in the console
• ❌ Deleting a connector that applications still use
  → Those applications are deleted too