Create system with OAuth-style callback

POST /systems/callback

Create a new system and execute an OAuth-style callback to an external URL. This endpoint is designed for external applications that want to integrate system creation into their workflow. The callback includes system information as query parameters.

Security Features:

Time-based state tokens: State tokens expire after 1 hour
One-shot protection: Each state token can only be used once (24-hour blacklist)
CSRF protection: State validation prevents cross-site request forgery

Callback Flow:

External page generates time-based state token with timestamp
External page redirects user to My Nethesis frontend with parameters
User authenticates via Logto if needed
Frontend calls this endpoint with system details and callback info
Backend creates system and executes GET callback to external URL
External page receives callback with system data in query parameters

application/json

Body Required

name string Required

System name
type string Required

System type

Values are ns8 or nsec.
callback_url string(uri) Required

External URL to callback with system creation results
callback_state string Required

Time-based state token for CSRF protection and replay prevention. Format: state_{base64-encoded-json} JSON contains: {timestamp: number, random: string}
custom_data object

Optional custom metadata for the system
Hide custom_data attribute Show custom_data attribute object
- * string Additional properties

Responses

201 application/json

System created successfully and callback executed
Hide response attributes Show response attributes object
- code integer
- message string
- data object
  
  Hide data attributes Show data attributes object
  
  system object
  
  Hide system attributes Show system attributes object
  
  id string
  
  System ID
  
  name string
  
  System name
  
  type string
  
  System type
  
  status string
  
  System operational status
  
  Values are online, offline, or maintenance.
  
  fqdn string
  
  Fully qualified domain name
  
  ipv4_address string
  
  IPv4 address
  
  ipv6_address string
  
  IPv6 address
  
  version string
  
  System version
  
  last_seen string(date-time)
  
  Last seen timestamp from inventory
  
  custom_data object
  
  Custom system data
  
  Additional properties are allowed.
  
  secret_hint string
  
  Last 4 characters of system secret for identification
  
  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
  
  user_name string
  
  Username 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
  
  callback_executed boolean
  
  Whether the callback was successfully executed
400 application/json

Bad request - invalid parameters or expired state token
Hide response attributes Show response attributes object
- code integer
- message string
  
  Values are invalid or already used state token, state token expired, or state token already used.
- data object
  
  Hide data attribute Show data attribute object
  
  error string
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

POST /systems/callback

curl \
 --request POST 'https://collect.your-domain.com/api/systems/callback' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"name":"Production Server","type":"ns8","callback_url":"https://external-app.com/callback","callback_state":"state_eyJ0aW1lc3RhbXAiOjE3MjU1MjUxMjM0NTYsInJhbmRvbSI6ImFiYzEyM2RlZjQ1NiJ9","custom_data":{"source":"external_app","created_via":"callback_flow"}}'

Request examples

{
  "name": "Production Server",
  "type": "ns8",
  "callback_url": "https://external-app.com/callback",
  "callback_state": "state_eyJ0aW1lc3RhbXAiOjE3MjU1MjUxMjM0NTYsInJhbmRvbSI6ImFiYzEyM2RlZjQ1NiJ9",
  "custom_data": {
    "source": "external_app",
    "created_via": "callback_flow"
  }
}

Response examples (201)

{
  "code": 201,
  "message": "system created successfully",
  "data": {
    "system": {
      "id": "4cf3053f-d0d5-4b10-b752-ff8f7b63c2f7",
      "name": "Production Server 01",
      "type": "ns8",
      "status": "online",
      "fqdn": "prod-web-01.example.com",
      "ipv4_address": "192.168.1.100",
      "ipv6_address": "2001:db8::1",
      "version": "2.1.4",
      "last_seen": "2025-07-10T10:30:00Z",
      "custom_data": {
        "tier": "web",
        "datacenter": "EU-West-1",
        "environment": "production"
      },
      "secret_hint": "a7b9",
      "created_at": "2025-07-01T09:00:00Z",
      "updated_at": "2025-07-10T10:30:00Z",
      "created_by": {
        "user_id": "usr_123456789",
        "user_name": "admin",
        "organization_id": "org_123456789",
        "organization_name": "Nethesis"
      },
      "heartbeat_status": "alive",
      "last_heartbeat": "2025-07-21T10:25:00Z",
      "heartbeat_minutes": 5
    },
    "callback_executed": true
  }
}

Response examples (400)

{
  "code": 400,
  "message": "state token expired",
  "data": {
    "error": "state token expired"
  }
}

Response examples (401)

{
  "code": 401,
  "message": "invalid token",
  "data": {}
}

Response examples (403)

{
  "code": 403,
  "message": "insufficient permissions",
  "data": {}
}