--- title: "POST | Create device" slug: "api-v2-post-create-device" updated: 2026-11-03T14:47:51Z published: 2026-11-03T14:47:51Z canonical: "docs.senhasegura.io/api-v2-post-create-device" --- > ## 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 device ## Description Create a device in PAM Core using the v2 API. A single request defines the device identity, its connectivity protocols, its criticality, its Network Connector association, and its session settings. Info This endpoint belongs to the A2A API v2 surface and is available from Segura™ version 4.2.9. Devices are served from the `/api/v2/platform` base path, not from `/api/v2/pam` like other v2 resources. In v1, creating and updating a device shared a single endpoint; v2 separates them. The v1 equivalent is documented in [POST | Create device](/v4-2/docs/api-post-create-device). --- ## Prerequisites - Authorization with **write** permission to PAM Core granted by the administrator in A2A. For more information, access [How to manage authorizations in A2A](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a). - The values sent in `type`, `vendor`, `product`, `site`, and `domain_name` must already be registered. Register them in [Device types](/v4-2/docs/pam-device-types), [Device vendors](/v4-2/docs/pam-device-vendors), [Device products](/v4-2/docs/pam-device-products), and [Device sites](/v4-2/docs/pam-device-sites). A value that isn't registered returns `422`. - To associate a Network Connector, the connector must already exist. For more information, access [How to configure devices on Network Connector](/v4-2/docs/network-connector-how-to-configure-devices-on-network-connector). --- ## Request `POST` `/api/v2/platform/devices` ### Request body Lookup fields are referenced by **name**, while the Network Connector and the administrator group are referenced by **id**. The response expands the id references into objects. | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | Yes | Name that identifies the device. | | `address` | string | Yes | IP address, hostname, or management URL of the device. | | `type` | string | Yes | Device type, by name. Must be a registered type. Example: `Server`, `Workstation`, `Network Device`, `Database`. | | `vendor` | string | Yes | Device vendor, by name. Must be a registered vendor. Example: `Oracle`, `Microsoft`, `Cisco`, `Red Hat`. | | `product` | string | Yes | Device product, by name. Must be a registered product, bound to the vendor. Example: `Oracle Linux VM`, `Windows Server 2022`. | | `site` | string | Yes | Site where the device is located, by name. Must be a registered site. Example: `SP-DC1`, `NY-DC2`, `AWS-US-EAST-1`. | | `domain_name` | string | No | Domain associated with the device, by name. Must be a registered domain. Example: `CORP`. Send `null` or omit when the device has no domain. | | `tags` | array[string] | No | Tags to associate with the device. Can be empty. | | `criticality` | string | No | Criticality level of the device. Allowed values: `low`, `medium`, `high`. Default: `medium`. | | `enable_remote_app` | boolean | No | Enables remote application support for the device. Default: `false`. | | `network_connector_id` | integer | No | Identification code of the Network Connector agent used to reach the device. Send `null` or omit when the device isn't reached through a connector. | | `administrator_group_id` | integer | No | Identification code of the administrator group of the device. Valid **only** when the access policy mode is static by device; sending it in dynamic policy mode returns `422`. | | `owner` | string | No | Username of the registered user who owns the device. | | `connectivities` | array of objects | No | Connectivity protocols to configure on the device. | | `connectivities[].protocol` | string | Yes | Connectivity protocol. Allowed values: `SSH`, `RDP`, `HTTPS`, `VNC`, `Telnet`, `SQL_Server`. | | `connectivities[].port` | integer | Yes | Port used by the protocol. | | `session_settings` | array of objects | No | Session automation settings applied when a session starts. | | `session_settings[].connectivity` | string | Yes | Protocol the setting applies to. Must match a protocol declared in `connectivities`, otherwise the request returns `422`. | | `session_settings[].expected_expression` | string | No | Expression the session waits for before sending `fill_in_value`. | | `session_settings[].fill_in_value` | string | No | Value sent when `expected_expression` is matched. | Attention This endpoint doesn't support the `Idempotency-Key` header. Resending a create request that already succeeded produces a **second device**, not the original one. Guard retries on the client side, for example by listing devices by `name` before retrying. Each create also queues a full access-policy processing pipeline so the device becomes visible in the web interface. The pipelines aren't coalesced: provisioning devices in bulk queues one pipeline per device. Take this into account when scripting mass provisioning. --- ### Example request `POST` `{{url}}/api/v2/platform/devices` #### Body ``` { "name": "db-prod-01", "address": "10.10.10.10", "type": "Server", "vendor": "Oracle", "product": "Oracle Linux VM", "site": "SP-DC1", "domain_name": "CORP", "tags": ["prod", "database"], "owner": "jdoe", "criticality": "high", "enable_remote_app": true, "network_connector_id": 12, "connectivities": [ { "protocol": "SSH", "port": 22 }, { "protocol": "RDP", "port": 3389 } ], "session_settings": [ { "connectivity": "SSH", "expected_expression": "$", "fill_in_value": "sudo su" } ] } ``` --- ## Response ``` HTTP/1.1 201 Created Location: /api/v2/platform/devices/55 ``` The `Location` header holds the path of the created device. The device is created with `active` set to `true`, and every protocol in `connectivities` starts with `connectable` set to `false` until the first connectivity test runs. Info From Segura™ version 4.2.10, the `201` response also carries an `ETag` header holding the initial version of the device. Use that value in the `If-Match` header of the first update. On version 4.2.9, the `201` response doesn't include the `ETag`: retrieve the device with [GET | List a device](/v4-2/docs/api-v2-get-list-a-device) first to obtain it. ### Example response body ``` { "data": { "id": "55", "device": { "name": "db-prod-01", "address": "10.10.10.10", "active": true, "type": "Server", "vendor": "Oracle", "product": "Oracle Linux VM", "site": "SP-DC1", "domain_name": "CORP", "tags": ["prod", "database"], "criticality": "high", "owner": { "name": "John Doe" }, "administrator_group": null, "enable_remote_app": true, "network_connector": { "id": "12", "name": "NC-SP-01", "port": "50001" }, "connectivities": [ { "protocol": "SSH", "port": 22, "connectable": false }, { "protocol": "RDP", "port": 3389, "connectable": false } ], "session_settings": [ { "connectivity": "SSH", "expected_expression": "$", "fill_in_value": "sudo su" } ] } }, "meta": { "links": { "self": "/api/v2/platform/devices/55" }, "actions": { "deactivate": "/api/v2/platform/devices/55/deactivate" } } } ``` --- ## Response body fields The response returns the created device with the same fields as [GET | List a device](/v4-2/docs/api-v2-get-list-a-device). Access that article for the full field tables. | Field | Type | Description | | --- | --- | --- | | `data` | object | The created device. | | `data.id` | string | Unique identification code assigned to the device by Segura™. Use this value in the path of every subsequent request for this device. | | `data.device` | object | Canonical attributes of the created device. | | `meta` | object | Navigation links and available actions. | | `meta.links.self` | string | URL of the created device. | | `meta.actions` | object | Actions available for the device in its current state. A newly created device is active, so only `deactivate` is listed. | --- ## Errors | HTTP code | Message | Possible cause | Solution | | --- | --- | --- | --- | | `400` | `api.request.malformed` | The body isn't valid JSON. | Check the payload syntax and the `Content-Type` header. | | `401` | `api.auth.token.invalid` | The access token is missing or has expired. | Request a new access token. | | `403` | `api.permission.denied` | The authorization doesn't have write permission to PAM Core resources. | Ask the administrator to check the authorization permissions in A2A, then generate a new token. | | `409` | `api.resource.conflict.duplicate_address` | A device already uses the management address sent in `address`, and duplicate addresses are not allowed. | Use a different address, or update the existing device instead. | | `422` | `api.validation.required_field` | A required field is missing. | Send `name`, `address`, `type`, `vendor`, `product`, and `site`. | | `422` | `api.validation.invalid_type` | A field has the wrong type. | Check the field types against the request body table. | | `422` | `api.validation.invalid_value` | A value is outside the allowed range, for example a `port` outside `1`–`65535`. | Correct the value and resend the request. | | `422` | `api.validation.invalid_reference` | A referenced type, vendor, product, site, domain, Network Connector, or user doesn't exist; `product` doesn't match the type; a `session_settings` protocol isn't declared in `connectivities`; or `administrator_group_id` was sent while the access policy mode is dynamic. | Register the value first, or remove the field. Check `error.details` to identify the field. | | `422` | `api.enum.invalid_value` | `criticality` received a value outside `low`, `medium`, `high`. | Send one of the allowed values. | | `422` | `api.validation.unknown_field` | The payload contains a field that isn't part of the contract. | Remove the unknown field. | | `429` | `rate_limit_exceeded` | The request rate limit was exceeded. | Wait the number of seconds given in the `Retry-After` header, then retry. | | `500` | `api.internal.error` | Internal server error. | Contact the Segura™ support team. | ### Example error response `422` a referenced vendor isn't registered: ``` { "error": { "code": "api.validation.invalid_reference", "message": "The referenced vendor does not exist.", "details": [ { "field": "vendor", "code": "api.validation.invalid_reference" } ] } } ``` ### Authentication errors | Message | Possible cause | Solution | | --- | --- | --- | | `Client authentication failed.` | Application authentication failure with the Segura™ server. | Check the authentication parameters (`Access Token URL`, `Client ID`, and `Client secret`) and request a new access token. | | `Invalid signature` | Failure in recognizing the client application URL. | Check the URL of the client application and resend the request. | | `No route matched with those values.` | Missing authorization header in the API request. | Request a new access token. | | `Request timed out.` | The request exceeded the timeout limit. | Check the connectivity between the source of the request and the Segura™ server. | --- ## Related documents - [API v2 — Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors) - [GET | List a device](/v4-2/docs/api-v2-get-list-a-device) - [PUT | Update device](/v4-2/docs/api-v2-put-update-device) - [PATCH | Update device](/v4-2/docs/api-v2-patch-update-device) - [POST | Deactivate device](/v4-2/docs/api-v2-post-deactivate-device) - [How to manage authorizations in A2A](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a) - [Device registration](/v4-2/docs/pam-device-device-registration)