/customers/{id}/transfer - Change the customer manager

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://api.my.nethesis.it/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json
{
  "my.nethesis.it MCP server": {
    "url": "https://api.my.nethesis.it/mcp"
  }
}

Close
PATCH /customers/{id}/transfer

Move the customer under another managing organization (reseller or distributor) by rewriting its custom_data.createdBy, in Logto and locally. Allowed to the Owner organization and to distributors, for a customer inside their hierarchy (403 otherwise). An unusable target is a 400 on key organization_id with message not_in_hierarchy or not_a_manager (not a reseller or distributor).

Systems, users, backups and alert history stay with the customer and follow it: visibility, rebranding and the alerting tenant derive from the manager. What belongs to the manager it leaves goes away: add-ons bought by that side stop renewing (they stay valid until they expire), its silences on the customer's systems are removed, alerts assigned to its users are released. The response carries the applied counters.

Path parameters

  • id string Required

    Customer Logto ID

application/json

Body Required

  • organization_id string Required

    Logto ID of the reseller or distributor that will manage the customer

Responses

  • 200 application/json

    Customer transferred

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

          Logto organization ID

        • name string
        • type string

          Values are owner, distributor, reseller, or customer.

      • from object
        Hide from attributes Show from attributes object
        • id string

          Logto organization ID

        • name string
        • type string

          Values are owner, distributor, reseller, or customer.

      • to object
        Hide to attributes Show to attributes object
        • id string

          Logto organization ID

        • name string
        • type string

          Values are owner, distributor, reseller, or customer.

      • systems_count integer

        Live systems of the customer, which move with it

      • users_count integer

        Users of the customer, who keep their access

      • addons array[object]
        Hide addons attributes Show addons attributes object
        • system_id string
        • system_name string
        • entitlement string
        • display_name string
        • scope string

          Application instance the grant is narrowed to, omitted for system-wide grants

        • valid_until string(date-time)

          Expiry, omitted for perpetual grants

        • purchased_by_organization_name string

          Buyer organization, omitted when unknown or outside the caller's hierarchy

        • renewal string

          What the transfer does to the shop renewal: continues when the buyer still manages the customer, stops when it does not (or is unknown) — the grant stays valid until it expires —, already_stopped by an earlier transfer, perpetual when the grant has no expiry.

          Values are continues, stops, already_stopped, or perpetual.

      • renewals_stopping integer

        Add-ons whose renewal stops (preview) or stopped (transfer)

      • silences_count integer

        Silences on the customer's systems in the current manager's alerting tenant, removed by the transfer

      • assignments_count integer

        Alerts of the customer assigned to users outside the new hierarchy, released by the transfer

      • warnings array[string]

        Steps that could not be checked or applied: silences_unavailable (preview), renewals_not_stopped, assignments_not_released, silences_not_cleared, handover_not_silenced, handover_not_cleared (transfer).

  • 400 application/json

    Bad request - validation error

    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

  • 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

  • 409 application/json

    The customer cannot be transferred in its current state. data.type is validation_error, on key transfer, with stable message codes: customer_is_suspended (reactivate it first), customer_not_synced (no Logto organization yet), same_organization (already managed by the target), target_is_suspended, transfer_in_progress (another transfer of the same customer is running).

    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

PATCH /customers/{id}/transfer
curl \
 --request PATCH 'https://my.nethesis.it/backend/api/customers/{id}/transfer' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{
  "organization_id": "5j8k2m4n6p8q"
}'
Request examples
{
  "organization_id": "5j8k2m4n6p8q"
}
Response examples (200)
{
  "code": 200,
  "message": "customer transferred successfully",
  "data": {
    "customer": {
      "id": "5j8k2m4n6p8q",
      "name": "ACME Reseller",
      "type": "reseller"
    },
    "from": {
      "id": "5j8k2m4n6p8q",
      "name": "ACME Reseller",
      "type": "reseller"
    },
    "to": {
      "id": "5j8k2m4n6p8q",
      "name": "ACME Reseller",
      "type": "reseller"
    },
    "systems_count": 4,
    "users_count": 2,
    "addons": [
      {
        "system_id": "0f6e6a3a-2f7e-4a64-9a4c-0d1d2c3b4a59",
        "system_name": "fw-headquarters",
        "entitlement": "nsec-blacklist",
        "display_name": "Advanced Threat Shield",
        "scope": "string",
        "valid_until": "2026-05-04T09:42:00Z",
        "purchased_by_organization_name": "ACME Reseller",
        "renewal": "continues"
      }
    ],
    "renewals_stopping": 1,
    "silences_count": 2,
    "assignments_count": 1,
    "warnings": [
      "string"
    ]
  }
}
Response examples (400)
{
  "code": 400,
  "message": "validation failed",
  "data": {
    "type": "validation_error",
    "errors": [
      {
        "key": "username",
        "message": "required",
        "value": "string"
      }
    ]
  }
}
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"
      }
    ]
  }
}
Response examples (409)
{
  "code": 409,
  "message": "validation failed",
  "data": {
    "type": "validation_error",
    "errors": [
      {
        "key": "transfer",
        "message": "same_organization"
      }
    ]
  }
}