Register a Node via the Trustgrid API

The Trustgrid API exposes a license generation endpoint that allows you to register appliance nodes programmatically — without using the portal UI. This is useful for automated deployments, infrastructure-as-code workflows, and scripted provisioning pipelines.

Overview

The traditional portal workflow for registering a new node appliance is:

1. Navigate to the Nodes page and click Add Node
2. Enter a node name and click Create License
3. Copy the generated license key and use it during node setup

The API-based registration replaces steps 1–2 with a single GET /node/license request and is otherwise identical: the returned license key is used the same way during node installation.

Prerequisites

• A Trustgrid API key (client ID and client secret). See API Access for instructions on generating one. For automated pipelines, consider using a Service User credential instead of a personal API key.
• The API key’s associated user must have the nodes::manage permission. This is included in the builtin-tg-admin policy.
• A Trustgrid node running a supported image that is ready to be registered.
• curl and (for the verification step) jq installed on the machine running these commands.

API Reference

Generate a Node License

Generates a license key that an appliance node uses to register with your Trustgrid organization.

Request

Authentication header

Authorization: trustgrid-token <CLIENT-ID>:<CLIENT-SECRET>

Query parameters

Response

Tutorial: Registering a Node via the API

Step 1 — Generate the License Key

Use curl to call the license endpoint with your API credentials and the desired node name. The -f flag causes curl to exit with a non-zero status on HTTP errors:

curl -sf \
  -H "Authorization: trustgrid-token YOUR-CLIENT-ID:YOUR-CLIENT-SECRET" \
  -G --data-urlencode "name=my-edge-node" \
  "https://api.trustgrid.io/node/license" \
  -o my-edge-node.lic

A successful response writes the license key to my-edge-node.lic. If the command fails (e.g., curl exits non-zero), check the HTTP response body for the error message — a 422 typically means the node name is already taken.

Step 2 — Use the License During Node Setup

The license key generated in Step 1 is used exactly the same way as a license downloaded from the portal. Apply it during Trustgrid node installation per the relevant deployment guide:

• Deploy to AWS
• Deploy to Azure
• Deploy to GCP
• Deploy to vSphere

Step 3 — Verify the Node Is Registered

Once the node has completed registration and connected to the Trustgrid control plane, you can confirm it is visible via the API. The example below uses jq to filter the node list:

curl -s \
  -H "Authorization: trustgrid-token YOUR-CLIENT-ID:YOUR-CLIENT-SECRET" \
  "https://api.trustgrid.io/node" | \
  jq '.[] | select(.name | startswith("my-edge-node")) | {name, uid, online, state}'

Example output for a successfully registered node:

{
  "name": "my-edge-node.your-domain.trustgrid.io",
  "uid": "abc12345-...",
  "online": false,
  "state": "ACTIVE"
}

Scripted Example

The following shell script combines Steps 1 and 2 into a reusable registration helper. It uses --data-urlencode to safely handle node names with spaces or special characters:

#!/usr/bin/env bash
# register-node.sh — generate a Trustgrid node license via the API
# Usage: ./register-node.sh <node-name> <output-file>

set -euo pipefail

NODE_NAME="${1:?Usage: $0 <node-name> <output-file>}"
OUTPUT_FILE="${2:?Usage: $0 <node-name> <output-file>}"

: "${TG_CLIENT_ID:?Set TG_CLIENT_ID environment variable}"
: "${TG_CLIENT_SECRET:?Set TG_CLIENT_SECRET environment variable}"

echo "Generating license for node: ${NODE_NAME}"

curl -sf \
  -H "Authorization: trustgrid-token ${TG_CLIENT_ID}:${TG_CLIENT_SECRET}" \
  -G --data-urlencode "name=${NODE_NAME}" \
  "https://api.trustgrid.io/node/license" \
  -o "${OUTPUT_FILE}"

echo "License saved to: ${OUTPUT_FILE}"

Run it by exporting your credentials as environment variables:

export TG_CLIENT_ID="your-client-id"
export TG_CLIENT_SECRET="your-client-secret"

./register-node.sh my-edge-node my-edge-node.lic

Related Resources

• API Access — how to generate and use API credentials
• Service Users — machine-to-machine credentials for automated integrations
• Remote Console Registration — register a node interactively from the console (no API required)
• Trustgrid API Documentation — full interactive API reference (Swagger UI)