--- title: "POST | Criar dispositivo" 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 | Criar dispositivo ## Descrição Crie um dispositivo no PAM Core utilizando a API v2. Uma única requisição define a identidade do dispositivo, seus protocolos de conectividade, sua criticidade, sua associação a um Network Connector e suas configurações de sessão. Info Este endpoint faz parte da superfície da API v2 do A2A e está disponível a partir da versão 4.2.9 do Segura™. Os dispositivos são servidos pelo caminho base `/api/v2/platform`, e não por `/api/v2/pam` como os demais recursos v2. Na v1, criar e atualizar um dispositivo compartilhavam um único endpoint; a v2 separa as duas operações. O equivalente v1 está documentado em [POST | Criar dispositivo](/v4-2/docs/api-post-create-device). --- ## Pré-requisitos - Autorização com permissão de **escrita** para o PAM Core, concedida pelo administrador no A2A. Para mais informações, acesse [Como gerenciar autorizações no A2A API v2](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a). - Os valores enviados em `type`, `vendor`, `product`, `site` e `domain_name` precisam estar previamente cadastrados. Cadastre-os em [Tipos](/v4-2/docs/pam-device-types), [Fabricantes](/v4-2/docs/pam-device-vendors), [Modelos](/v4-2/docs/pam-device-products) e [Sites](/v4-2/docs/pam-device-sites). Um valor não cadastrado retorna `422`. - Para associar um Network Connector, o conector precisa existir previamente. Para mais informações, acesse [Como configurar dispositivos no Network Connector](/v4-2/docs/network-connector-how-to-configure-devices-on-network-connector). --- ## Requisição `POST` `/api/v2/platform/devices` ### Corpo da requisição Os campos de lookup são referenciados por **nome**, enquanto o Network Connector e o grupo administrador são referenciados por **id**. A resposta expande as referências por id em objetos. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `name` | string | Sim | Nome que identifica o dispositivo. | | `address` | string | Sim | Endereço IP, hostname ou URL de gerenciamento do dispositivo. | | `type` | string | Sim | Tipo do dispositivo, por nome. Precisa ser um tipo cadastrado. Exemplo: `Server`, `Workstation`, `Network Device`, `Database`. | | `vendor` | string | Sim | Fabricante do dispositivo, por nome. Precisa ser um fabricante cadastrado. Exemplo: `Oracle`, `Microsoft`, `Cisco`, `Red Hat`. | | `product` | string | Sim | Modelo do dispositivo, por nome. Precisa ser um modelo cadastrado e vinculado ao fabricante. Exemplo: `Oracle Linux VM`, `Windows Server 2022`. | | `site` | string | Sim | Site onde o dispositivo está localizado, por nome. Precisa ser um site cadastrado. Exemplo: `SP-DC1`, `NY-DC2`, `AWS-US-EAST-1`. | | `domain_name` | string | Não | Domínio associado ao dispositivo, por nome. Precisa ser um domínio cadastrado. Exemplo: `CORP`. Envie `null` ou omita quando o dispositivo não tiver domínio. | | `tags` | array[string] | Não | Tags a associar ao dispositivo. Pode ser vazio. | | `criticality` | string | Não | Nível de criticidade do dispositivo. Valores permitidos: `low`, `medium`, `high`. Padrão: `medium`. | | `enable_remote_app` | boolean | Não | Habilita o suporte a aplicação remota para o dispositivo. Padrão: `false`. | | `network_connector_id` | integer | Não | Código de identificação do agent do Network Connector utilizado para alcançar o dispositivo. Envie `null` ou omita quando o dispositivo não for alcançado por um conector. | | `administrator_group_id` | integer | Não | Código de identificação do grupo administrador do dispositivo. Válido **apenas** quando o modo de política de acesso é estático por dispositivo; enviá-lo no modo de política dinâmica retorna `422`. | | `owner` | string | Não | Nome de usuário do usuário cadastrado responsável pelo dispositivo. | | `connectivities` | array de objetos | Não | Protocolos de conectividade a configurar no dispositivo. | | `connectivities[].protocol` | string | Sim | Protocolo de conectividade. Valores permitidos: `SSH`, `RDP`, `HTTPS`, `VNC`, `Telnet`, `SQL_Server`. | | `connectivities[].port` | integer | Sim | Porta utilizada pelo protocolo. | | `session_settings` | array de objetos | Não | Configurações de automação de sessão aplicadas no início de uma sessão. | | `session_settings[].connectivity` | string | Sim | Protocolo ao qual a configuração se aplica. Precisa corresponder a um protocolo declarado em `connectivities`; caso contrário, a requisição retorna `422`. | | `session_settings[].expected_expression` | string | Não | Expressão que a sessão aguarda antes de enviar `fill_in_value`. | | `session_settings[].fill_in_value` | string | Não | Valor enviado quando `expected_expression` é encontrada. | Atenção Este endpoint não suporta o cabeçalho `Idempotency-Key`. Reenviar uma requisição de criação que já foi bem-sucedida cria um **segundo dispositivo**, e não retorna o original. Controle as retentativas no lado do cliente, por exemplo listando os dispositivos por `name` antes de repetir a requisição. Cada criação também enfileira uma pipeline completa de processamento de políticas de acesso, para que o dispositivo se torne visível na interface web. As pipelines não são agrupadas: provisionar dispositivos em lote enfileira uma pipeline por dispositivo. Leve isso em conta ao automatizar provisionamento em massa. --- ### Exemplo de requisição `POST` `{{url}}/api/v2/platform/devices` #### Corpo ``` { "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" } ] } ``` --- ## Resposta ``` HTTP/1.1 201 Created Location: /api/v2/platform/devices/55 ``` O cabeçalho `Location` traz o caminho do dispositivo criado. O dispositivo é criado com `active` igual a `true`, e cada protocolo em `connectivities` começa com `connectable` igual a `false` até que o primeiro teste de conectividade seja executado. Info A partir da versão 4.2.10 do Segura™, a resposta `201` também traz o cabeçalho `ETag` com a versão inicial do dispositivo. Utilize esse valor no cabeçalho `If-Match` da primeira atualização. Na versão 4.2.9, a resposta `201` não inclui o `ETag`: consulte o dispositivo com [GET | Listar um dispositivo (v2)](/v4-2/docs/api-v2-get-list-a-device) antes, para obtê-lo. ### Exemplo de corpo da resposta ``` { "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" } } } ``` --- ## Campos do corpo da resposta A resposta retorna o dispositivo criado com os mesmos campos de [GET | Listar um dispositivo (v2)](/v4-2/docs/api-v2-get-list-a-device). Acesse esse documento para as tabelas completas de campos. | Campo | Tipo | Descrição | | --- | --- | --- | | `data` | object | O dispositivo criado. | | `data.id` | string | Código de identificação único atribuído ao dispositivo pelo Segura™. Use este valor no caminho de todas as requisições seguintes para este dispositivo. | | `data.device` | object | Atributos canônicos do dispositivo criado. | | `meta` | object | Links de navegação e ações disponíveis. | | `meta.links.self` | string | URL do dispositivo criado. | | `meta.actions` | object | Ações disponíveis para o dispositivo em seu estado atual. Um dispositivo recém-criado está ativo, por isso apenas `deactivate` é listado. | --- ## Erros | Código HTTP | Mensagem | Causa possível | Solução | | --- | --- | --- | --- | | `400` | `api.request.malformed` | O corpo não é um JSON válido. | Verifique a sintaxe do payload e o cabeçalho `Content-Type`. | | `401` | `api.auth.token.invalid` | O token de acesso está ausente ou expirou. | Solicite um novo token de acesso. | | `403` | `api.permission.denied` | A autorização não tem permissão de escrita para os recursos do PAM Core. | Peça ao administrador para verificar as permissões da autorização no A2A e gere um novo token. | | `409` | `api.resource.conflict.duplicate_address` | Outro dispositivo já utiliza o endereço de gerenciamento enviado em `address`, e endereços duplicados não são permitidos. | Utilize um endereço diferente ou atualize o dispositivo existente. | | `422` | `api.validation.required_field` | Um campo obrigatório está ausente. | Envie `name`, `address`, `type`, `vendor`, `product` e `site`. | | `422` | `api.validation.invalid_type` | Um campo tem o tipo incorreto. | Verifique os tipos dos campos na tabela do corpo da requisição. | | `422` | `api.validation.invalid_value` | Um valor está fora do intervalo permitido, por exemplo uma `port` fora de `1`–`65535`. | Corrija o valor e reenvie a requisição. | | `422` | `api.validation.invalid_reference` | Um tipo, fabricante, modelo, site, domínio, Network Connector ou usuário referenciado não existe; o `product` não corresponde ao tipo; um protocolo de `session_settings` não está declarado em `connectivities`; ou o `administrator_group_id` foi enviado com o modo de política de acesso dinâmico. | Cadastre o valor antes ou remova o campo. Consulte `error.details` para identificar o campo. | | `422` | `api.enum.invalid_value` | O `criticality` recebeu um valor fora de `low`, `medium`, `high`. | Envie um dos valores permitidos. | | `422` | `api.validation.unknown_field` | O payload contém um campo que não faz parte do contrato. | Remova o campo desconhecido. | | `429` | `rate_limit_exceeded` | O limite de requisições foi excedido. | Aguarde o número de segundos indicado no cabeçalho `Retry-After` e tente novamente. | | `500` | `api.internal.error` | Erro interno do servidor. | Entre em contato com a equipe de suporte da Segura™. | ### Exemplo de resposta de erro `422` um fabricante referenciado não está cadastrado: ``` { "error": { "code": "api.validation.invalid_reference", "message": "The referenced vendor does not exist.", "details": [ { "field": "vendor", "code": "api.validation.invalid_reference" } ] } } ``` ### Erros de autenticação | Mensagem | Causa possível | Solução | | --- | --- | --- | | `Client authentication failed.` | Falha na autenticação da aplicação com o servidor Segura™. | Verifique os parâmetros de autenticação (`Access Token URL`, `Client ID` e `Client secret`) e solicite um novo token de acesso. | | `Invalid signature` | Falha no reconhecimento da URL da aplicação cliente. | Verifique a URL da aplicação cliente e reenvie a requisição. | | `No route matched with those values.` | Cabeçalho de autorização ausente na requisição da API. | Solicite um novo token de acesso. | | `Request timed out.` | A requisição excedeu o limite de tempo. | Verifique a conectividade entre a origem da requisição e o servidor Segura™. | --- ## Documentos relacionados - [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors) - [GET | Listar um dispositivo (v2)](/v4-2/docs/api-v2-get-list-a-device) - [PUT | Atualizar dispositivo (v2)](/v4-2/docs/api-v2-put-update-device) - [PATCH | Atualizar dispositivo (v2)](/v4-2/docs/api-v2-patch-update-device) - [POST | Desativar dispositivo (v2)](/v4-2/docs/api-v2-post-deactivate-device) - [Como gerenciar autorizações no A2A API v2](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a) - [Cadastro de dispositivo](/v4-2/docs/pam-device-device-registration)