/systems/{id}/regenerate-secret - Regenerate system secret

POST /systems/{id}/regenerate-secret
Bearer auth

Regenerate authentication secret for a specific system. Users can regenerate secrets for systems created by their organization based on hierarchical permissions.

Path parameters

  • id string Required

    System ID

Responses

  • 200 application/json

    System secret regenerated successfully

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object
      Hide data attributes Show data attributes object
      • id string

        System ID

      • name string

        System name

      • type string | null

        System type (auto-detected by collect service, null until first inventory collection)

        Values are ns8 or nsec.

      • status string

        System operational status (defaults to 'unknown', auto-updated by collect service)

        Values are unknown, online, offline, or deleted.

      • fqdn string

        Fully qualified domain name

      • ipv4_address string

        IPv4 address

      • ipv6_address string

        IPv6 address

      • version string

        System version

      • system_key string

        Auto-generated unique commercial system key. Hidden (empty string) until system is registered.

      • organization_id string

        Organization ID to which this system belongs

      • organization_name string

        Organization name to which this system belongs (resolved from distributors, resellers, or customers)

      • custom_data object

        Custom system data

        Additional properties are allowed.

      • system_secret string

        Auto-generated system secret token in format my_. (only returned during creation/regeneration, never stored or displayed again)

      • notes string

        Additional notes or description for the system

      • created_at string(date-time)

        System creation timestamp

      • updated_at string(date-time)

        System last update timestamp

      • created_by object
        Hide created_by attributes Show created_by attributes object
        • user_id string

          User ID who created the system

        • name string

          Full name of the user who created the system

        • email string

          Email of the user who created the system

        • organization_id string

          Organization ID of the creator

        • organization_name string

          Organization name of the creator

      • heartbeat_status string

        System heartbeat status (alive=<15min, dead=>15min, zombie=never communicated)

        Values are alive, dead, or zombie.

      • last_heartbeat string(date-time)

        Last heartbeat timestamp

      • heartbeat_minutes integer

        Minutes since last heartbeat

      • registered_at string(date-time) | null

        Registration timestamp. NULL means not yet registered, non-NULL means system registered at that time. When NULL, system_key is hidden.
  • 401 application/json

    Unauthorized - invalid or missing token

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object | null
  • 403 application/json

    Forbidden - insufficient permissions

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object | null
  • 404 application/json

    Resource not found

    Hide response attributes Show response attributes object
    • code integer

      HTTP error code

    • message string

      Error message

    • data object
      Hide data attributes Show data attributes object
      • type string

        Type of error

        Values are validation_error or external_api_error.

      • errors array[object]
        Hide errors attributes Show errors attributes object
        • key string

          Field name that failed validation

        • message string

          Error code or message

        • value string

          Value that failed validation

      • details

        Additional error details
POST /systems/{id}/regenerate-secret 
curl \
 --request POST 'https://collect.your-domain.com/api/systems/sys_123456789/regenerate-secret' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "code": 200,
  "message": "system secret regenerated successfully",
  "data": {
    "id": "4cf3053f-d0d5-4b10-b752-ff8f7b63c2f7",
    "name": "Production Server 01",
    "type": "nsec",
    "status": "unknown",
    "fqdn": "prod-web-01.example.com",
    "ipv4_address": "192.168.1.100",
    "ipv6_address": "2001:db8::1",
    "version": "2.1.4",
    "system_key": "ABC123DEF456",
    "organization_id": "org_123456789",
    "organization_name": "Acme Corporation",
    "custom_data": {
      "tier": "web",
      "datacenter": "EU-West-1",
      "environment": "production"
    },
    "system_secret": "my_a1b2c3d4e5f6g7h8i9j0.k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0",
    "notes": "Production web server for EU region",
    "created_at": "2025-07-01T09:00:00Z",
    "updated_at": "2025-07-10T10:30:00Z",
    "created_by": {
      "user_id": "53h5zxpwu4vc",
      "name": "Edoardo Super",
      "email": "edoardo.spadoni@nethesis.it",
      "organization_id": "lbswt1rxdhbz",
      "organization_name": "Nethesis Italia"
    },
    "heartbeat_status": "alive",
    "last_heartbeat": "2025-07-21T10:25:00Z",
    "heartbeat_minutes": 5,
    "registered_at": "2025-11-06T10:30:00Z"
  }
}
Response examples (401) 
{
  "code": 401,
  "message": "invalid token",
  "data": {}
}
Response examples (403) 
{
  "code": 403,
  "message": "insufficient permissions",
  "data": {}
}
Response examples (404) 
{
  "code": 400,
  "message": "validation failed",
  "data": {
    "type": "validation_error",
    "errors": [
      {
        "key": "username",
        "message": "required",
        "value": "string"
      }
    ]
  }
}