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:
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
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.
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.
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
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.
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.
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:
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:
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.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.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
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
Acesso aplicação para aplicação, como recuperar uma credencial sem uma pessoa
O cofre de credenciais, de onde esses endpoints leem
Trilha de auditoria, onde as chamadas de API ficam registradas
Campos de configuração, a URL do site que os clientes devem endereçar
Atualizado
Isto foi útil?