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.

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.

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.

• 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:

curl -s \
  -H "X-API-KEY: <your-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 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: dirección base, endpoints y errores

• Usuarios: el usuario en cuyo nombre actúa una clave, y Block Dashboard Logins

• Roles y permisos: lo que puede hacer el usuario de la clave

• Registro de auditoría: los cambios hechos con una clave