/systems/register - Register system with system_secret

POST /systems/register
Bearer auth

Public endpoint for external systems to register themselves using their system_secret token. This endpoint does NOT require authentication - the system_secret itself provides authentication.

Token Format: my_<public_part>.<secret_part>

Workflow:

  1. User creates system in management UI → receives system_secret (one time only)
  2. External system uses system_secret to register → receives system_key
  3. External system uses system_key for future operations (inventory, heartbeat)

Important:

  • Systems can only be registered once
  • Deleted systems cannot be registered
  • The system_secret is validated using Argon2id hashing
application/json

Body Required

  • system_secret string Required

    System secret token in format my_.

Responses

  • 200 application/json

    System registered successfully

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

        System key to use for future operations

      • registered_at string(date-time)

        Timestamp when system was registered

      • message string
  • 400 application/json

    Invalid system secret format

    Hide response attributes Show response attributes object
    • code integer
    • message string
  • 401 application/json

    Invalid system secret (authentication failed)

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

    System has been deleted

    Hide response attributes Show response attributes object
    • code integer
    • message string
  • 409 application/json

    System is already registered

    Hide response attributes Show response attributes object
    • code integer
    • message string
  • 500 application/json

    Internal server error

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object | null
POST /systems/register 
curl \
 --request POST 'https://api.your-domain.com/api/systems/register' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"system_secret":"my_a1b2c3d4e5f6g7h8i9j0.k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0"}'
Request examples 
{
  "system_secret": "my_a1b2c3d4e5f6g7h8i9j0.k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0"
}
Response examples (200) 
{
  "code": 200,
  "message": "system registered successfully",
  "data": {
    "system_key": "my_sys_a1b2c3d4e5f6g7h8",
    "registered_at": "2025-11-06T10:30:00Z",
    "message": "system registered successfully"
  }
}
Response examples (400) 
{
  "code": 400,
  "message": "invalid system secret format"
}
Response examples (401) 
{
  "code": 401,
  "message": "invalid system secret"
}
Response examples (403) 
{
  "code": 403,
  "message": "system has been deleted"
}
Response examples (409) 
{
  "code": 409,
  "message": "system is already registered"
}
Response examples (500) 
{
  "code": 500,
  "message": "internal server error",
  "data": {}
}