API
Dónde está la especificación de la API, las tres formas en que un cliente se autentica, las convenciones comunes a todos los endpoints y qué cubre cada familia.
Qué es esto y cuándo usarlo
La solución expone una API REST sobre HTTPS. La propia consola es cliente de ella: cada pantalla que usted usa llama a los mismos endpoints que llamaría un sistema externo, y por eso todo lo que la consola hace es alcanzable de forma programática.
Úsela para registrar activos desde un CMDB, recuperar una credencial dentro de una canalización, exportar registros de auditoría a un data warehouse o gestionar altas y bajas desde un sistema de identidad.
Dónde está la especificación
Dos direcciones en su propia instancia, ambas generadas a partir de la versión que está realmente en ejecución:
https://<su-instancia>/api/docs
Documentación interactiva
Recorrer los endpoints y probar una llamada
https://<su-instancia>/api/swagger.json
Especificación OpenAPI 2.0
Generar un cliente en cualquier lenguaje
Todos los endpoints están bajo el prefijo /api/v1/, y la API responde únicamente por HTTPS. Un cliente que no puede validar el certificado de la instancia falla en la capa de transporte antes de que la autenticación importe, de modo que un certificado autofirmado debe ser confiado por la máquina que llama.
Cómo se autentica un cliente
No hay acceso anónimo. Existen tres mecanismos, y portan identidades distintas.
Firma con clave de acceso
Un usuario de la consola
Perfil › Claves de acceso, que emite un ID y un secreto
Firma con aplicación de integración
Una aplicación
Registrada por un administrador, que emite un ID y un secreto
Token Bearer
Un usuario de la consola
POST /api/v1/authentication/auth/ con usuario y contraseña
Firmar una solicitud
Ambos mecanismos de firma usan HTTP Signature con HMAC-SHA256. El cliente construye una cadena de firma a partir del destino de la solicitud y la fecha, la firma con su secreto y envía el resultado en la cabecera Authorization.
Tres detalles deciden si la llamada funciona:
La query string forma parte de la cadena de firma. Firme el destino de la solicitud exactamente como será enviado, con los parámetros y en el mismo orden.
La fecha debe estar en RFC 7231, en inglés, en GMT. Un cliente que corre en una máquina con idioma distinto del inglés, y que formatea la fecha en su propio idioma, produce una cabecera que el servidor rechaza. Es el fallo de integración más frecuente, y sólo aparece fuera de entornos en inglés.
Una aplicación de integración añade
X-Source: datadike-pam. Esa cabecera es la que distingue una aplicación de la clave de acceso de un usuario, y sin ella la solicitud se interpreta como esto último.
Token Bearer
Un token obtenido en el endpoint de inicio de sesión se envía como Authorization: Bearer <token>. Porta los permisos del usuario al que fue emitido y tiene vida corta, lo que lo hace adecuado para un script interactivo e inadecuado para una rutina desatendida. Para cualquier cosa que corra sin una persona presente, prefiera la firma.
Clientes listos para usar
El producto entrega un cliente funcional y su documentación para seis lenguajes, servidos por la propia instancia en la pestaña SDKs de la aplicación de integración. Cada uno implementa la firma descrita arriba.
Python
requests, httpsig
Java
Ninguna. Sólo la biblioteca estándar
Go
Ninguna. Sólo la biblioteca estándar
Node.js
axios
PowerShell
Ninguna. Sólo cmdlets nativos
curl
Ninguna
Convenciones comunes a todos los endpoints
Paginación
Las colecciones se paginan con limit y offset, y responden con un sobre consistente:
Búsqueda, orden y filtro
search
Búsqueda de texto libre en los campos buscables del recurso
order
Campo por el que ordenar. Prefije con - para invertir
nombre del campo
Filtro por valor exacto. Qué campos son filtrables varía según el recurso
Descubrir los campos de un recurso
Una solicitud OPTIONS a una colección devuelve los metadatos de los campos del recurso: nombres, tipos, si cada uno es obligatorio y las opciones disponibles. Es la vía más rápida para conocer un payload sin leer la especificación entera, y refleja sus propios permisos.
Formatos de exportación
Las colecciones se renderizan en JSON, CSV o XLSX. Añada format=csv o format=xlsx a un GET, y la respuesta trae una fila de cabecera con los mismos nombres de columna que exporta la consola.
Idioma
Las respuestas honran la cabecera Accept-Language e informan lo que usaron en Content-Language. Los mensajes de error, las etiquetas de campo y los textos de validación vuelven traducidos.
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 una llamada autenticada como usuario de la consola, la preferencia de idioma de ese usuario prevalece sobre la cabecera.
Organizaciones
Una instancia puede albergar varias organizaciones, y la mayoría de los recursos pertenece a una. Las solicitudes indican la organización en la cabecera X-PAM-ORG. Un cliente que la omite opera en la organización predeterminada, lo que es causa frecuente de que una llamada tenga éxito y no devuelva nada.
Familias de endpoints
Todas las familias siguientes están cubiertas por la especificación de su instancia. El recuento de operaciones mide superficie, no importancia.
Sesiones y conectores
/terminal/
249
Sesiones en vivo, grabaciones, endpoints de conexión, applets, hosts publicadores
Activos
/assets/
229
Hosts, bases de datos, dispositivos, nube, plataformas, nodos, zonas, descubrimiento
Cuentas
/accounts/
159
Cuentas gestionadas, plantillas, rotación, descubrimiento, respaldo, aplicaciones de integración
Autenticación
/authentication/
100
Inicio de sesión, MFA, claves de acceso, claves SSH, passkeys, tokens de conexión
Solicitudes
/tickets/
96
Pedidos de acceso, flujos de aprobación, aprobadores
Autorizaciones
/perms/
77
Quién puede alcanzar qué activo con qué cuenta
Roles y permisos
/rbac/
75
Roles, vínculos de rol, catálogo de permisos
Usuarios
/users/
70
Usuarios, grupos, sincronización con el directorio
Automatización
/ops/
64
Trabajos, comandos ad hoc, playbooks, historial de ejecución
Control de acceso
/acls/
58
Filtros de comandos, reglas de inicio de sesión, reglas de método de conexión
Gateways
/brokers/
37
Gateways inversos y los destinos alcanzables a través de ellos
Etiquetas
/labels/
34
Etiquetas y lo que las porta
Auditoría
/audits/
28
Registros de inicio de sesión, registros de operación, recuperaciones de credencial, transferencias de archivo
Notificaciones
/notifications/
26
Canales, suscripciones, plantillas de mensaje
Configuración
/settings/
25
Configuración del sistema
Análisis de comportamiento
/ueba/
20
Hallazgos de comportamiento y sus reglas
Informes
/reports/
19
Definiciones de informe, ejecuciones, descargas
Bóveda
/vault/
16
Credenciales guardadas y compartidas a mano, en carpetas
Organizaciones
/orgs/
12
Inquilinos y sus miembros
Errores
Los fallos responden con un cuerpo JSON que trae un detail legible por personas y un code estable:
400
Un payload que no pasó la validación. El cuerpo nombra los campos con problema
401
Sin credencial, token vencido, o una firma que el servidor no pudo verificar
403
Una identidad válida, sin permiso para este recurso
404
El recurso no existe, o pertenece a otra organización
Trate el code, y no el detail, porque el detail se traduce y el code no.
Cómo verificar que alcanza la API
Tres comprobaciones, en el orden que encuentra problemas más rápido:
Llame al endpoint de salud. No exige credencial, lo que lo convierte en la prueba más rápida de que la red, el nombre de host y TLS funcionan:
Una instancia sana responde con
"status": true, junto con el estado de la base de datos y de la caché.Llame a una colección con su credencial y confirme que vuelve el sobre.
GET /api/v1/users/users/?limit=1es una elección segura, y un 401 aquí, con la instancia sana, apunta a la credencial y no a la conexión.Repita la llamada desde la máquina que ejecutará la integración. Las direcciones de origen permitidas de una aplicación se aplican, así que una llamada que funciona en su estación puede ser rechazada en el servidor que la necesita.
Errores comunes
401 con una firma que parece correcta
La fecha se formateó en el idioma de la máquina, o el reloj está desfasado
Formatee la fecha en inglés, en GMT, y mantenga el reloj del host sincronizado
401 sólo cuando hay query string
La firma cubrió la ruta sin los parámetros
Firme el destino de la solicitud exactamente como se envía
Una aplicación de integración no se autentica como nadie
Falta el X-Source: datadike-pam
Añada la cabecera
La llamada tiene éxito pero la colección vuelve vacía
El cliente está operando en la organización predeterminada
Envíe X-PAM-ORG con la organización pretendida
La llamada funciona en su estación y falla en el servidor
Las direcciones de origen permitidas de la aplicación no incluyen ese servidor
Añada la dirección a la aplicación
403 con una credencial que funciona
El usuario o la aplicación no tiene permiso para ese recurso
Revise el rol, o el alcance de cuentas de la aplicación
No se puede alcanzar /api/docs
Se está direccionando la instancia por un nombre que el cliente no resuelve, o TLS está fallando
Use la misma dirección que Configuración del sistema › General › URL del sitio
Páginas relacionadas
Acceso de aplicación a aplicación, cómo recuperar una credencial sin una persona
La bóveda de credenciales, de donde leen esos endpoints
Rastro de auditoría, donde quedan registradas las llamadas a la API
Campos de configuración, la URL del sitio a la que los clientes deben dirigirse
Atualizado
Isto foi útil?