For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Pular para o conteúdo
September 22 — Documentation updated for compatibility with the latest PAM version (5.3.0).

API

Onde fica a especificação da API, as três formas de um cliente se autenticar, as convenções que todos os endpoints compartilham e o que cada família cobre.

O que é isto e quando usar

A solução expõe uma API REST sobre HTTPS. O próprio console é cliente dela: toda tela que você usa chama os mesmos endpoints que um sistema externo chamaria, e é por isso que tudo o que o console faz pode ser feito programaticamente.

Use a API para cadastrar ativos a partir de um CMDB, recuperar uma credencial dentro de uma esteira, exportar registros de auditoria para um data warehouse ou conduzir admissão e desligamento a partir de um sistema de identidade.

Onde fica a especificação

Dois endereços na sua própria instância, ambos gerados a partir da versão que está de fato em execução:

Endereço
O que é
Para que serve

https://<sua-instancia>/api/docs

Documentação interativa

Navegar pelos endpoints e testar uma chamada

https://<sua-instancia>/api/swagger.json

Especificação OpenAPI 2.0

Gerar um cliente em qualquer linguagem

Leia a especificação da sua própria instância, e não de qualquer lista anotada em outro lugar. Ela corresponde à versão com a qual você está integrando, coisa que uma página de wiki não tem como garantir.

Todos os endpoints ficam sob o prefixo /api/v1/, e a API responde somente por HTTPS. Um cliente que não consegue validar o certificado da instância falha na camada de transporte antes que a autenticação importe, então um certificado autoassinado precisa ser confiado pela máquina que chama.

Como um cliente se autentica

Não existe acesso anônimo. Três mecanismos estão disponíveis, e eles carregam identidades diferentes.

Mecanismo
Identidade
Como a credencial é obtida

Assinatura por chave de acesso

Um usuário do console

Perfil › Chave de Acesso, que emite um ID e um segredo

Assinatura por aplicação de integração

Uma aplicação

Cadastrada por um administrador, que emite um ID e um segredo

Token Bearer

Um usuário do console

POST /api/v1/authentication/auth/ com usuário e senha

Assinando uma requisição

Os dois mecanismos de assinatura usam HTTP Signature com HMAC-SHA256. O cliente monta uma string de assinatura a partir do alvo da requisição e da data, assina com o seu segredo e envia o resultado no cabeçalho Authorization.

Três detalhes decidem se a chamada funciona:

  • A query string faz parte da string de assinatura. Assine o alvo da requisição exatamente como ele será enviado, com os parâmetros e na mesma ordem.

  • A data precisa estar em RFC 7231, em inglês, em GMT. Um cliente rodando em máquina com idioma diferente do inglês, que formate a data no idioma local, produz um cabeçalho que o servidor rejeita. Essa é a falha de integração mais comum, e ela só aparece fora de ambientes em inglês.

  • Uma aplicação de integração acrescenta X-Source: datadike-pam. É esse cabeçalho que distingue uma aplicação da chave de acesso de um usuário, e sem ele a requisição é interpretada como a segunda.

Token Bearer

Um token obtido no endpoint de login é enviado como Authorization: Bearer <token>. Ele carrega as permissões do usuário para quem foi emitido e tem vida curta, o que o torna adequado a um script interativo e inadequado a uma rotina desassistida. Para qualquer coisa que rode sem uma pessoa presente, prefira a assinatura.

Clientes prontos

O produto entrega um cliente funcional e a respectiva documentação para seis linguagens, servidos pela própria instância na aba SDKs da aplicação de integração. Cada um implementa a assinatura descrita acima.

Linguagem
Dependências

Python

requests, httpsig

Java

Nenhuma. Apenas a biblioteca padrão

Go

Nenhuma. Apenas a biblioteca padrão

Node.js

axios

PowerShell

Nenhuma. Apenas cmdlets nativos

curl

Nenhuma

Convenções que todos os endpoints compartilham

Paginação

Coleções são paginadas com limit e offset, e respondem com um envelope consistente:

Busca, ordenação e filtro

Parâmetro
O que faz

search

Busca textual livre nos campos pesquisáveis do recurso

order

Campo para ordenar. Prefixe com - para inverter

nome do campo

Filtro por valor exato. Quais campos são filtráveis varia por recurso

Descobrindo os campos de um recurso

Uma requisição OPTIONS a uma coleção devolve os metadados dos campos do recurso: nomes, tipos, se cada um é obrigatório e as opções disponíveis. É o caminho mais rápido para conhecer um payload sem ler a especificação inteira, e reflete as suas próprias permissões.

Formatos de exportação

Coleções são renderizadas em JSON, CSV ou XLSX. Acrescente format=csv ou format=xlsx a um GET, e a resposta traz uma linha de cabeçalho com os mesmos nomes de coluna que o console exporta.

Idioma

As respostas honram o cabeçalho Accept-Language e informam o que usaram em Content-Language. Mensagens de erro, rótulos de campo e textos de validação voltam traduzidos.

Enviado
Recebido

en

Authentication credentials were not provided.

pt-br

As credenciais de autenticação não foram fornecidas.

es

Las credenciales de autenticación no se proveyeron.

fr

Informations d'authentification non fournies.

Para uma chamada autenticada como usuário do console, a preferência de idioma desse usuário prevalece sobre o cabeçalho.

Organizações

Uma instância pode abrigar várias organizações, e a maioria dos recursos pertence a uma delas. As requisições informam a organização no cabeçalho X-PAM-ORG. Um cliente que o omite opera na organização padrão, o que é causa frequente de uma chamada ter sucesso e não devolver nada.

Famílias de endpoints

Todas as famílias abaixo estão cobertas pela especificação da sua instância. A contagem de operações mede superfície, não importância.

Família
Prefixo
Operações
O que cobre

Sessões e conectores

/terminal/

249

Sessões ao vivo, gravações, endpoints de conexão, applets, hosts publicadores

Ativos

/assets/

229

Hosts, bancos de dados, dispositivos, nuvem, plataformas, nós, zonas, descoberta

Contas

/accounts/

159

Contas gerenciadas, modelos, rotação, descoberta, backup, aplicações de integração

Autenticação

/authentication/

100

Login, MFA, chaves de acesso, chaves SSH, passkeys, tokens de conexão

Solicitações

/tickets/

96

Pedidos de acesso, fluxos de aprovação, aprovadores

Autorizações

/perms/

77

Quem pode alcançar qual ativo com qual conta

Papéis e permissões

/rbac/

75

Papéis, vínculos de papel, catálogo de permissões

Usuários

/users/

70

Usuários, grupos, sincronização com diretório

Automação

/ops/

64

Trabalhos, comandos ad hoc, playbooks, histórico de execução

Controle de acesso

/acls/

58

Filtros de comando, regras de login, regras de método de conexão

Gateways

/brokers/

37

Gateways reversos e os alvos alcançáveis por eles

Etiquetas

/labels/

34

Etiquetas e o que as carrega

Auditoria

/audits/

28

Registros de login, logs de operação, retiradas de credencial, transferências de arquivo

Notificações

/notifications/

26

Canais, assinaturas, modelos de mensagem

Configurações

/settings/

25

Configuração do sistema

Análise comportamental

/ueba/

20

Achados comportamentais e suas regras

Relatórios

/reports/

19

Definições de relatório, execuções, downloads

Cofre

/vault/

16

Credenciais guardadas e compartilhadas manualmente, em pastas

Organizações

/orgs/

12

Tenants e seus membros

Erros

As falhas respondem com um corpo JSON que traz um detail legível por pessoas e um code estável:

Status
Causa habitual

400

Um payload que não passou na validação. O corpo nomeia os campos com problema

401

Sem credencial, token expirado, ou assinatura que o servidor não conseguiu verificar

403

Uma identidade válida, sem permissão para este recurso

404

O recurso não existe, ou pertence a outra organização

Trate o code, e não o detail, porque o detail é traduzido e o code não.

Como verificar que você alcança a API

Três checagens, na ordem que encontra problemas mais rápido:

  1. Chame o endpoint de saúde. Ele não exige credencial, o que o torna a prova mais rápida de que rede, nome de host e TLS estão funcionando:

    Uma instância saudável responde com "status": true, junto do estado do banco de dados e do cache.

  2. Chame uma coleção com a sua credencial e confirme que o envelope volta. GET /api/v1/users/users/?limit=1 é uma escolha segura, e um 401 aqui, com a instância saudável, aponta para a credencial e não para a conexão.

  3. Repita a chamada a partir da máquina que vai rodar a integração. Os endereços de origem permitidos de uma aplicação são aplicados, então uma chamada que funciona na sua estação pode ser recusada no servidor que precisa dela.

Erros comuns

Sintoma
Causa
Correção

401 com uma assinatura que parece correta

A data foi formatada no idioma da máquina, ou o relógio está fora de hora

Formate a data em inglês, em GMT, e mantenha o relógio do host sincronizado

401 apenas quando há query string

A assinatura cobriu o caminho sem os parâmetros

Assine o alvo da requisição exatamente como ele é enviado

Uma aplicação de integração não se autentica como ninguém

Falta o X-Source: datadike-pam

Acrescente o cabeçalho

A chamada tem sucesso mas a coleção volta vazia

O cliente está operando na organização padrão

Envie X-PAM-ORG com a organização pretendida

A chamada funciona na sua estação e falha no servidor

Os endereços de origem permitidos da aplicação não incluem esse servidor

Acrescente o endereço à aplicação

403 com uma credencial que funciona

O usuário ou a aplicação não tem permissão para aquele recurso

Verifique o papel, ou o escopo de contas da aplicação

Não se consegue alcançar /api/docs

A instância está sendo endereçada por um nome que o cliente não resolve, ou o TLS está falhando

Use o mesmo endereço de Configurações do Sistema › Geral › URL do site

Páginas relacionadas

Atualizado

Isto foi útil?