> For the complete documentation index, see [llms.txt](https://wiki.datadike.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.datadike.com/es/pam/reference/api.md). # 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: | Dirección | Qué es | Para qué sirve | | ----------------------------------------- | -------------------------- | ------------------------------------------- | | `https:///api/docs` | Documentación interactiva | Recorrer los endpoints y probar una llamada | | `https:///api/swagger.json` | Especificación OpenAPI 2.0 | Generar un cliente en cualquier lenguaje | {% hint style="info" %} Lea la especificación de **su propia instancia**, y no de cualquier lista anotada en otro sitio. Corresponde a la versión con la que usted está integrando, algo que una página de wiki no puede garantizar. {% endhint %} 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. | Mecanismo | Identidad | Cómo se obtiene la credencial | | --------------------------------------- | ------------------------ | ------------------------------------------------------------- | | **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`. ``` (request-target): get /api/v1/assets/hosts/?limit=10 date: Wed, 23 Sep 2026 20:44:35 GMT ``` ``` Authorization: Signature keyId="",algorithm="hmac-sha256", headers="(request-target) date",signature="" Date: Wed, 23 Sep 2026 20:44:35 GMT ``` 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 `. 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. {% hint style="warning" %} Una clave de acceso porta todos los permisos del usuario que la posee, así que es tan poderosa como el rol de esa persona. Una aplicación de integración, en cambio, está limitada dos veces: a las cuentas que puede leer y a las direcciones de origen desde las que puede llamar. **Para acceso de máquina, prefiera una aplicación de integración.** {% endhint %} ### 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. | Lenguaje | Dependencias | | ---------- | ------------------------------------ | | 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: ```json { "count": 412, "next": "...", "previous": null, "results": [] } ``` ### Búsqueda, orden y filtro | Parámetro | Qué hace | | ------------------ | ------------------------------------------------------------------------- | | `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. | Enviado | Devuelto | | ------- | ------------------------------------------------------ | | `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. | Familia | Prefijo | Operaciones | Qué cubre | | -------------------------- | ------------------ | ----------- | -------------------------------------------------------------------------------------------------------------- | | 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: ```json { "detail": "Authentication credentials were not provided.", "code": "not_authenticated" } ``` | Estado | Causa habitual | | ------ | ------------------------------------------------------------------------------ | | 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: 1. **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: ```bash curl -s "https:///api/health/" ``` Una instancia sana responde con `"status": true`, junto con el estado de la base de datos y de la caché. 2. **Llame a una colección con su credencial** y confirme que vuelve el sobre. `GET /api/v1/users/users/?limit=1` es una elección segura, y un 401 aquí, con la instancia sana, apunta a la credencial y no a la conexión. 3. **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 | Síntoma | Causa | Corrección | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | | 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](/es/pam/administration/integrations/application-to-application.md), cómo recuperar una credencial sin una persona * [La bóveda de credenciales](/es/pam/administration/accounts/vault.md), de donde leen esos endpoints * [Rastro de auditoría](/es/pam/administration/audit/audit-trail.md), donde quedan registradas las llamadas a la API * [Campos de configuración](/es/pam/reference/configuration-fields.md), la URL del sitio a la que los clientes deben dirigirse