Una clave API permite que tus propios sistemas lean y actualicen tu señalización a través de la API de EasySignage. Una clave actúa sobre una cuenta con exactamente el acceso que le otorgues, y puedes eliminarla en cualquier momento.
Antes de empezar
- Tu cuenta necesita acceso a la API, incluido en los planes Premium y Enterprise. En otros planes la página muestra un aviso con un botón Mejorar plan.
- Inicia sesión en la cuenta sobre la que actuará la clave. Una clave queda vinculada a la cuenta que estés gestionando en el momento de crearla.
Crear una clave API
- Ve a Ajustes > Claves de API.
- Selecciona Crear clave de API.
- Ingresa un Nombre que indique para qué es la clave, por ejemplo el sistema que la usará.
- Configura cada área de tu cuenta como Sin acceso, Solo lectura o Acceso completo.
- Selecciona Crear clave de API.
- Copia la clave.
Advertencia: La clave se muestra una sola vez y no se puede recuperar después. Cópiala antes de cerrar el cuadro de diálogo. Si la pierdes, elimina la clave y crea una nueva.
Elegir a qué puede acceder una clave
Cada clave tiene sus propios permisos, configurados área por área:
- Pantallas
- Grupos
- Pared de video
- Listas de reproducción
- Canales
- Zonas
- Sincronizar grupos
- Programas (horarios)
- Carpetas
- Activos de medios
- Webhooks: suscripciones de webhook, que envían datos de tu cuenta a una URL. Una clave de solo lectura no puede añadir una.
Cada área se configura en uno de tres niveles:
| Nivel | Qué puede hacer la clave |
|---|---|
| Sin acceso | Nada en esa área |
| Solo lectura | Leer el área, sin hacer cambios |
| Acceso completo | Leer el área y hacer cambios |
Otorga al menos un área. Crear clave de API permanece deshabilitado mientras todas las áreas estén configuradas como Sin acceso. Otorga a una clave solo las áreas que el sistema que la usa realmente necesita.
Autenticar una solicitud
Envía la clave en un encabezado X-API-Key:
X-API-Key: ds_api_...
La clave resuelve tanto la marca como la cuenta por sí sola, así que los encabezados X-Account y X-Domain se ignoran en una solicitud con clave API. Una clave no se puede redirigir a una cuenta distinta.
Abrir la documentación de la API
- Ve a Ajustes > Claves de API.
- Selecciona Abrir documentación de la API.
La documentación se abre en una nueva pestaña e inicia sesión automáticamente. No tiene un inicio de sesión aparte, así que ábrela desde Ajustes > Claves de API en lugar de guardarla como marcador.
Revisar una clave existente
- Ve a Ajustes > Claves de API.
- Selecciona el icono de vista en la clave.
Cada clave de la lista muestra una versión enmascarada de la credencial, las áreas a las que puede acceder, cuándo se creó y cuándo se usó por última vez. El cuadro de diálogo de detalles también muestra quién la creó. La clave completa no vuelve a mostrarse después de crearse. Una clave revocada con una versión anterior de la página muestra la etiqueta Revocada; ya no funciona y se puede eliminar.
Reemplazar una clave
No existe una acción de rotación. Para reemplazar una clave, crea primero la nueva clave, traslada tus sistemas a ella y luego elimina la anterior. Crear el reemplazo primero significa que nada deja de funcionar mientras haces la transición.
Eliminar una clave
- Ve a Ajustes > Claves de API.
- Selecciona el icono de eliminar en la clave.
- Confirma la eliminación.
Advertencia: Eliminar una clave surte efecto de inmediato y no se puede deshacer. Cualquier cosa que use esa clave deja de funcionar en su próxima solicitud. Los detalles de la clave se conservan en el registro de tu cuenta.
Límites
- Una cuenta puede tener hasta 10 claves API.
- El nombre de una clave puede tener hasta 100 caracteres.
- Se debe otorgar al menos un área antes de poder crear una clave.
Solucionar problemas con las claves API
El acceso a la API solo está disponible en los planes Premium y Enterprise.
La cuenta no tiene acceso a la API. Consulta tu plan en la página de precios o contacta con soporte.
Ha alcanzado el número máximo de claves de API.
La cuenta ya tiene 10 claves. Elimina una que ya no uses y luego crea la nueva clave.
La clave se creó pero no se pudo mostrar. Elimínela y cree una nueva.
La clave existe pero nunca se mostró, así que no se puede usar. Elimínala y crea un reemplazo.
No se pudo abrir la documentación de la API. Inténtelo de nuevo.
No se pudo crear el enlace de inicio de sesión para la documentación. Inténtalo de nuevo y recarga el panel de control si sigue fallando.
Una solicitud devuelve 403
Una solicitud con clave API que falla en cualquier verificación responde
403con el cuerpo vacío. Una clave desconocida, una clave alterada, una clave eliminada, un permiso que no se otorgó a la clave y una cuenta sin acceso a la API se ven todos igual, a propósito, para que la API no se pueda usar para descubrir qué claves existen. Verifica que la clave siga apareciendo en Ajustes > Claves de API, que el área que estás llamando esté otorgada y que la cuenta siga teniendo acceso a la API.