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.

Prerequisites

Authorization with write permission to PAM Core granted by the administrator in A2A. For more information, access 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, Device vendors, Device products, and 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.

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 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. 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.