---
title: "POST | Create Network Connector agent"
slug: "api-v2-post-create-network-connector-agent"
updated: 2026-10-14T16:27:21Z
published: 2026-10-14T16:27:21Z
canonical: "docs.senhasegura.io/api-v2-post-create-network-connector-agent"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senhasegura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a).
- A valid OAuth 2.0 access token. For more information, access [How to authenticate an application in A2A](/v4-2/docs/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](/v4-2/docs/api-v2-put-update-network-connector-agent) or [PATCH | Update Network Connector agent](/v4-2/docs/api-v2-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](/v4-2/docs/api-v2-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](/v4-2/docs/api-v2-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](/v4-2/docs/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"
        }
    ]
}
```

---

## Related documents

- [GET | List all Network Connector agents](/v4-2/docs/api-v2-get-list-all-network-connector-agents)
- [GET | List a Network Connector agent by [id]](/v4-2/docs/api-v2-get-list-a-network-connector-agent)
- [PATCH | Update Network Connector agent](/v4-2/docs/api-v2-patch-update-network-connector-agent)
- [POST | Deactivate Network Connector agent](/v4-2/docs/api-v2-post-deactivate-network-connector-agent)
- [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors)
- [How to manage authorizations in A2A for API v2](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a)