Registration Tokens

Registration tokens let servers, agents, and scripts self-register as inventory nodes without needing user credentials. This is the primary way to automate your inventory from deploy pipelines, monitoring systems, and infrastructure scripts.

How It Works

1. A team admin creates a registration token with optional restrictions (max uses, allowed kinds)
2. The token is distributed to servers or scripts
3. Each server calls the /api/register-node endpoint with the token and its details
4. Nodebyte creates (or updates) a node in the team’s inventory

Registration is idempotent — if a node with the same hostname already exists in the team, it gets updated instead of duplicated. This makes it safe to run registration on every boot or deploy.

Creating a Token

From the Dashboard

1. Navigate to Tokens in the sidebar
2. Click Create Token
3. Configure the token:
   • Name — descriptive label (e.g. “CI/CD Pipeline”, “Ansible Playbook”)
   • Max Uses — optional limit on how many nodes can register with this token (leave empty for unlimited)
   • Allowed Kinds — optional restriction on what kind of node can register (e.g. only server)
4. Copy the generated token — it’s only shown once

Via the API

curl -X POST http://localhost:8000/api/teams/{team_id}/registration-tokens \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ansible Playbook",
    "max_uses": 50,
    "allowed_kinds": ["server"]
  }'

Registering a Node

Use the registration token to register a node from any script or automation tool:

curl -X POST http://localhost:8000/api/register-node \
  -H "Content-Type: application/json" \
  -d '{
    "token": "your-registration-token",
    "name": "web-prod-03",
    "hostname": "web-prod-03.example.com",
    "ip_address": "10.0.1.53",
    "kind": "server",
    "tags": ["production", "web"],
    "meta": {"region": "us-east", "provider": "aws"}
  }'

The endpoint returns the created or updated node.

Inventory Scripts

Nodebyte includes ready-made scripts that use registration tokens to auto-discover and register infrastructure:

Docker Containers

REGISTRATION_TOKEN="your-token" \
NODEBYTE_URL="http://localhost:8000" \
bash scripts/docker-inventory.sh

Discovers all running Docker containers and registers each as a node.

LXD Containers

REGISTRATION_TOKEN="your-token" \
NODEBYTE_URL="http://localhost:8000" \
bash scripts/lxd-inventory.sh

Kubernetes Pods

REGISTRATION_TOKEN="your-token" \
NODEBYTE_URL="http://localhost:8000" \
bash scripts/kubernetes-inventory.sh

DigitalOcean Droplets

REGISTRATION_TOKEN="your-token" \
NODEBYTE_URL="http://localhost:8000" \
DO_API_TOKEN="your-do-token" \
bash scripts/digitalocean-inventory.sh

CI/CD Integration

Add node registration to your deploy pipeline so inventory stays current:

# GitHub Actions example
- name: Register with Nodebyte
  run: |
    curl -X POST ${{ secrets.NODEBYTE_URL }}/api/register-node \
      -H "Content-Type: application/json" \
      -d '{
        "token": "${{ secrets.NODEBYTE_REG_TOKEN }}",
        "name": "${{ github.event.repository.name }}",
        "hostname": "${{ env.DEPLOY_HOST }}",
        "kind": "service",
        "tags": ["production", "${{ github.event.repository.name }}"],
        "meta": {"commit": "${{ github.sha }}", "deployed_at": "${{ github.event.head_commit.timestamp }}"}
      }'

Managing Tokens

From the Tokens page, you can:

• View all active tokens with their usage counts
• Revoke a token to immediately block further registrations

API Reference

Method	Endpoint	Description
POST	/api/teams/{team_id}/registration-tokens	Create a token
GET	/api/teams/{team_id}/registration-tokens	List tokens
DELETE	/api/teams/{team_id}/registration-tokens/{token_id}	Revoke a token
POST	/api/register-node	Register a node (uses token, no auth header needed)