POST | Desativar dispositivo

Descrição

Desative um dispositivo cadastrado no PAM Core utilizando a API v2. Um dispositivo desativado deixa de aceitar operações de escrita e ações, e continua disponível para leitura com active igual a false.

Alerta

Desativar um dispositivo também desativa todas as credenciais ativas vinculadas a ele, e a resposta informa quantas foram afetadas em affected_credentials. Reativar o dispositivo com POST | Ativar dispositivo (v2) não restaura essas credenciais: reativá-las é responsabilidade do integrador. Verifique as credenciais vinculadas a um dispositivo antes de desativá-lo, pois automações que dependem delas deixarão de funcionar.

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.
Um dispositivo ativo. Desativar um dispositivo que já está inativo retorna 409.
Nenhuma sessão ativa do dispositivo no proxy. Uma sessão ativa bloqueia a desativação e retorna 409.

Requisição

POST /api/v2/platform/devices/{id}/deactivate

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, um dispositivo era desativado por DELETE | Desativar dispositivo; na v2 esta ação a substitui, e a API v2 não implementa o método DELETE para dispositivos.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	integer	Sim	Código de identificação único do dispositivo. Nota: este valor é atribuído pelo Segura® em POST \| Criar dispositivo (v2).

Esta ação não recebe corpo de requisição e não exige o cabeçalho If-Match requerido por PUT | Atualizar dispositivo (v2) e PATCH | Atualizar dispositivo (v2).

Uma sessão ativa no proxy bloqueia a desativação. Uma credencial sob custódia, ou seja, com checkout ativo, não bloqueia: a custódia permanece sob responsabilidade do integrador que realizou o checkout.

Exemplo de requisição

POST {{url}}/api/v2/platform/devices/55/deactivate

Resposta

HTTP/1.1 200 OK

Diferente de POST | Ativar dispositivo (v2), que retorna 204, esta ação retorna um corpo para que o chamador visualize o impacto da propagação.

Exemplo de corpo da resposta

{
    "data": {
        "affected_credentials": 12
    },
    "meta": {
        "links": {
            "self": "/api/v2/platform/devices/55/deactivate"
        }
    }
}

Campos do corpo da resposta

Campo	Tipo	Descrição
`data`	object	Resultado da desativação.
`data.affected_credentials`	integer	Número de credenciais ativas que foram desativadas em decorrência da desativação do dispositivo. Retorna `0` quando o dispositivo não tinha credenciais ativas vinculadas.
`meta`	object	Links de navegação.
`meta.links`	object	Links de navegação da requisição.
`meta.links.self`	string	URL da requisição atual.

Erros

Código HTTP	Mensagem	Causa possível	Solução
`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.
`404`	`api.resource.not_found`	O dispositivo não existe ou pertence a outro tenant.	Verifique o código de identificação enviado no caminho.
`409`	`api.resource.conflict.active_sessions`	Existe uma sessão ativa do dispositivo no proxy.	Aguarde o encerramento da sessão, ou encerre-a, e reenvie a requisição.
`409`	`api.resource.conflict.already_inactive`	O dispositivo já está inativo.	Nenhuma ação é necessária, o dispositivo já está no estado solicitado.
`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

409 existe uma sessão ativa do dispositivo no proxy:

{
    "error": {
        "code": "api.resource.conflict.active_sessions",
        "message": "Cannot modify or deactivate device while active sessions exist on the proxy."
    }
}

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