> 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/sonar/administration/settings/api-keys.md). # Claves de API Cree claves de API para scripts e integraciones, vincule cada clave a un usuario cuyo rol define lo que puede hacer, fíjele una caducidad y revóquela. ## Qué es y cuándo usarlo Una clave de API permite que un script o una integración llame a la API de SONAR sin un inicio de sesión interactivo. Cada clave pertenece a un usuario de la consola y actúa como ese usuario: tiene los permisos del rol del usuario, y el **Client & Site Access** del rol se le aplica igual que al usuario. Use una clave para alimentar una CMDB con un inventario, para abrir tickets a partir de alertas, o para ejecutar un script en dispositivos desde un programador externo. Las claves se gestionan en **Admin Center › Settings**, en la pestaña **API Keys**. {% hint style="warning" %} Una clave se autentica por sí sola, sin contraseña ni código de autenticador. Trátela como una contraseña: guárdela en una bóveda de secretos, nunca en un script que otros puedan leer, y fíjele una caducidad. {% endhint %} ## Antes de empezar * Para abrir **Admin Center › Settings**: el permiso **View Core Settings**. * Para ver las claves: **List API Keys**. Para crearlas, editarlas o eliminarlas: **Manage API Keys**. * Para elegir el usuario de la clave: **List Accounts**. * Un usuario para la clave. Para una integración, cree un usuario dedicado con un rol que conceda solo lo que la integración necesita, y marque en él **Block Dashboard Logins** para que no pueda iniciar sesión en la consola. Sus claves siguen funcionando. Vea [Usuarios](/es/sonar/administration/identities/users.md). * La dirección de la API de su instalación, que se entrega con ella. Esta página la escribe como `https://api.example.com`. ## Pasos ### Crear una clave 1. Abra **Admin Center › Settings** y seleccione la pestaña **API Keys**. 2. Haga clic en **Add key**. El cuadro de diálogo **Add API Key** indica `API Key will be generated on save`. 3. Escriba un **Name** que diga para qué sirve la clave, por ejemplo `cmdb-sync`. 4. Elija el **User** en cuyo nombre actúa la clave. 5. Opcional: fije **Key Expiration (Not required)**. Pasada esa fecha, la clave deja de funcionar. 6. Haga clic en **Submit**. 7. En la lista, haga clic en el icono de copiar de la fila de la clave (**Copy API Key to clipboard**) y guarde la clave en su bóveda de secretos. ### Enviar la clave en cada solicitud Ponga la clave en el encabezado `X-API-KEY` de cada solicitud: ```bash curl -s \ -H "X-API-KEY: " \ -H "Content-Type: application/json" \ "https://api.example.com/agents/?page=1&page_size=10" ``` La solicitud se ejecuta con los permisos del usuario de la clave. Vea [API](/es/sonar/reference/api.md) para los endpoints. ### Cambiar una clave 1. Haga doble clic en la fila de la clave, o haga clic con el botón derecho sobre ella y elija **Edit**. 2. Cambie **Name**, **User** o **Key Expiration (Not required)**. El campo **Key** muestra la clave y no se puede cambiar. 3. Haga clic en **Submit**. ### Revocar una clave 1. Haga clic con el botón derecho en la fila de la clave y elija **Delete**. 2. Confirme **Delete** en el cuadro de diálogo **Delete API key: ...?**. La clave deja de funcionar de inmediato. Para suspender todas las claves de un usuario, desmarque **Active** en el usuario, en **Admin Center › Users**. Eliminar el usuario elimina sus claves. ## Qué debe ver La clave aparece en la lista con su **Name**, su **User**, su **Expiration** y su fecha de **Created**. Hay mensajes que confirman cada acción: `The API Key was added`, `The API Key was edited`, `The API Key was deleted` y `Key was copied to clipboard!`. ## Cómo verificar que funcionó 1. Ejecute la llamada `curl` anterior desde la máquina que ejecutará la integración. Una clave válida devuelve una página JSON de dispositivos con `count`, `total_pages`, `next`, `previous` y `results`. 2. Haga un cambio a través de la API, por ejemplo edite la descripción de un dispositivo, y abra **Reports & Audits › Audits**. La entrada **Modify Object** lleva el nombre de usuario del usuario de la clave. 3. Tras eliminar una clave o desactivar su usuario, repita la llamada. Debe fallar con el estado 401. ## Errores comunes | Síntoma | Causa | Solución | | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | 401 con `Invalid token.` | La clave es incorrecta, está incompleta o se eliminó | Vuelva a copiar la clave de la lista, o cree una nueva | | 401 con `The token has expired.` | **Key Expiration** está en el pasado | Edite la clave y fije una fecha posterior, o vacíe el campo | | 401 con `User inactive or deleted.` | El usuario de la clave está desactivado | Active el usuario, o pase la clave a un usuario activo | | 401 con `Authentication credentials were not provided.` | Falta el encabezado o está mal escrito | Envíe la clave en `X-API-KEY` | | 403 con `You do not have permission to perform this action.` | El rol del usuario no tiene el permiso, o el dispositivo está fuera de los clientes y sitios del rol | Amplíe el rol, o use la clave de un usuario cuyo rol cubra la llamada | | `name: api key with this name already exists.` | Los nombres de las claves son únicos | Elija otro nombre | | `name: Ensure this field has no more than 25 characters.` | El nombre tiene más de 25 caracteres | Acórtelo | | `user: This field is required.` | No se eligió ningún usuario | Elija el **User** | ## Referencia de campos | Campo | Qué hace | Valores aceptados | Valor por defecto | | ----------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------- | --------------------- | | Name | Identifica la clave en la lista y en el registro de auditoría | Texto, único, hasta 25 caracteres | (sin valor) | | User | El usuario de la consola en cuyo nombre actúa la clave. La clave tiene los permisos de ese usuario | Cualquier usuario de la consola | (sin valor) | | Key | El secreto en sí, generado al guardar | 32 caracteres, solo lectura | Generado | | Key Expiration (Not required) | Fecha y hora a partir de las cuales la clave deja de funcionar | Una fecha y hora, o vacío | Vacío (sin caducidad) | | Created | Cuándo se creó la clave | Se muestra en la lista | (sin valor) | ## Páginas relacionadas * [API](/es/sonar/reference/api.md): dirección base, endpoints y errores * [Usuarios](/es/sonar/administration/identities/users.md): el usuario en cuyo nombre actúa una clave, y **Block Dashboard Logins** * [Roles y permisos](/es/sonar/administration/identities/roles.md): lo que puede hacer el usuario de la clave * [Registro de auditoría](/es/sonar/administration/audit/audit-trail.md): los cambios hechos con una clave