POST | Create Network Connector agent

Description

Create an agent of the Network Connector by sending only its name. Segura® assigns the port and returns the fingerprint used to install the agent.

The new agent is active. Use its id in the network_connector_id field to link a device to it.

Each request creates a new agent. The endpoint does not support the Idempotency-Key header, so resending the same request creates another agent.

Prerequisites

An application with the PAM resource permission set to Read and write, granted by the administrator in A2A. For more information, access How to manage authorizations in A2A for API v2.
A valid OAuth 2.0 access token. For more information, access How to authenticate an application in A2A.

Request

POST /api/v2/platform/network-connector/agents

Headers

Header	Required	Value
`Content-Type`	Yes	`application/json`

Request body

Field	Type	Required	Description
`name`	string	Yes	Name of the agent. Leading and trailing spaces are removed. Maximum: 255 characters. Must be unique among the agents of the Network Connector, including deactivated agents.

Send only name. Segura® assigns id, port, active, and fingerprint: sending any of them returns 422.

Example request

POST {{url}}/api/v2/platform/network-connector/agents

{
    "name": "agent-rj-02"
}

Response

HTTP/1.1 201 Created

The response includes these headers:

Location: path of the new agent.
ETag: version of the agent's current state. Send it in the If-Match header of PUT | Update Network Connector agent or PATCH | Update Network Connector agent.

Example response body

{
    "data": {
        "id": "12",
        "network_connector_agent": {
            "name": "agent-rj-02",
            "port": "30003",
            "active": true,
            "fingerprint": "EXAMPLE-FINGERPRINT-0003"
        }
    },
    "meta": {
        "links": {
            "self": "/api/v2/platform/network-connector/agents/12"
        },
        "actions": {
            "deactivate": "/api/v2/platform/network-connector/agents/12/deactivate"
        }
    }
}

Response body fields

Field	Type	Description
`data`	object	The created agent.
`data.id`	string	Unique identification code of the agent, returned as a string. Use it in the path of the other agent endpoints. To link a device, send it as an integer in the device's `network_connector_id` field.
`data.network_connector_agent`	object	Attributes of the agent.
`data.network_connector_agent.name`	string	Name of the agent, without leading and trailing spaces.
`data.network_connector_agent.port`	string	Port assigned to the agent by Segura®, returned as a string.
`data.network_connector_agent.active`	boolean	Always `true` for a new agent.
`data.network_connector_agent.fingerprint`	string	Value used to install the agent. Store it securely and share it only with whoever installs the agent.
`meta`	object	Navigation links and available actions.
`meta.links.self`	string	Path of the created agent.
`meta.actions.deactivate`	string	Path to deactivate the agent. For more information, access POST \| Deactivate Network Connector agent.

Errors

HTTP code	Message	Possible cause	Solution
`400`	`api.request.bad_request`	The body is not valid JSON.	Check the payload syntax.
`403`	`api.auth.insufficient_permission`	The application's PAM resource permission is Read-only.	Ask the administrator to set the PAM resource permission to Read and write in A2A.
`404`	`api.resource.not_found`	The Network Connector does not exist in the environment.	Check that the Network Connector is set up in Segura®.
`415`	`api.request.unsupported_media_type`	The `Content-Type` header is not `application/json`.	Send `Content-Type: application/json`.
`422`	`api.validation.required_field`	`name` is missing, empty, or contains only spaces.	Send a name for the agent.
`422`	`api.validation.invalid_type`	`name` is not a string.	Send `name` as a string.
`422`	`api.validation.invalid_value`	`name` has more than 255 characters.	Send a name with up to 255 characters.
`422`	`api.validation.duplicate`	Another agent, active or deactivated, already uses the name.	Choose a different name. To find the names in use, access GET \| List all Network Connector agents with `active=true` and with `active=false`.
`422`	`patch.field.not_allowed`	The body contains `id`, `port`, `active`, or `fingerprint`.	Send only `name`.
`422`	`api.validation.unknown_field`	The body contains a field that is not part of the contract.	Send only `name`.
`503`	`network_connector.port_allocation_failed`	Segura® could not assign a port to the agent. The agent is not created.	Wait the number of seconds given in the `Retry-After` header, then resend the request.
`503`	`network_connector.broker_unavailable`	The Network Connector service is temporarily unavailable. The agent is not created.	Wait the number of seconds given in the `Retry-After` header, then resend the request. If the error persists, contact the Segura® support team.
`503`	`network_connector.credential_unavailable`	Segura® could not complete the creation. The agent is not created.	Wait the number of seconds given in the `Retry-After` header, then resend the request. If the error persists, contact the Segura® support team.

For authentication errors, rate limits, and the error response format, access API v2 - Conventions and shared behaviors.

Example error response

422 another agent already uses the name:

{
    "code": "api.validation.duplicate",
    "message": "A network connector agent with this name already exists.",
    "details": [
        {
            "field": "name",
            "code": "api.validation.duplicate"
        }
    ]
}