Este artículo explica cómo funcionan las credenciales, los alcances de escritura y los catálogos de una aplicación registrada, y qué condiciones deben cumplirse para que la aplicación pueda crear, editar o eliminar campañas y crear contenidos a través de la API de SMARTFENSE.
¿Qué es una aplicación registrada?
Una aplicación representa a un sistema externo que se conecta con la API de SMARTFENSE. Cada aplicación tiene sus propias credenciales y solo puede utilizar los endpoints que habilitan sus alcances.
Las aplicaciones se gestionan desde Configuración > Integraciones > Aplicaciones registradas.
Para conocer el proceso completo de registro, consulte el artículo Integración de APIs en SMARTFENSE.
Autenticación
La API de SMARTFENSE utiliza los flujos de OAuth 2.0 Client Credentials y Authorization Code para autenticar las solicitudes.
- Client Credentials: diseñado para interacciones de servidor a servidor. La aplicación accede a la API sin que un usuario esté presente.
- Authorization Code: se utiliza cuando la aplicación necesita acceder a recursos en nombre de un usuario. Requiere la interacción y el consentimiento explícito de ese usuario a través de un navegador.
Para que una solicitud sea aceptada:
- Todas las solicitudes deben estar autenticadas.
- Todas las solicitudes deben realizarse a través de HTTPS.
- Cada solicitud debe incluir un bearer token en el encabezado
Authorization.
Importante: cualquier llamada realizada sobre HTTP simple fallará.
Credenciales
- Client ID y Client Secret: identifican a la aplicación al solicitar un token de acceso.
- Tipo de cliente: indica dónde se guardan las credenciales.
- Confidencial: las credenciales se guardan en un servidor.
- Público: las credenciales se guardan del lado del cliente.
- Tipo de concesión de autorización: define el flujo de OAuth 2.0 con el que la aplicación obtiene su token.
- Client Credentials: para integraciones de servidor a servidor, sin intervención de un usuario.
- Authorization Code: cuando un usuario debe autorizar a la aplicación desde el navegador. En este caso, complete las URIs de redirección.
Importante: el Client Secret solo se muestra al registrar la aplicación. Cópielo y guárdelo en un lugar seguro, porque no puede recuperarse más adelante.
Alcances
Los alcances son los permisos de la aplicación. Por seguridad, seleccione solo los necesarios para los endpoints que va a utilizar.
Alcances de campañas
Crear, editar y eliminar campañas son tres alcances distintos. Así es posible, por ejemplo, permitir que una aplicación cree campañas sin permitirle eliminarlas.
Solo un usuario con permiso para administrar campañas puede:
- Otorgar esos alcances.
- Modificar o eliminar una aplicación que ya los tiene.
Alcance para crear contenidos
Solo un usuario con permiso para administrar contenidos puede:
- Otorgar el alcance para crear contenidos.
- Modificar o eliminar una aplicación que ya lo tiene.
¿En nombre de quién actúa la aplicación?
Aunque con Client Credentials no hay un usuario presente al momento de la solicitud, los alcances de escritura siempre quedan vinculados a una persona. La aplicación los utiliza mientras esa persona siga activa y conserve el permiso correspondiente:
| Tipo de concesión de autorización | Usuario por el que actúa la aplicación |
|---|---|
| Client Credentials | El usuario que registró la aplicación. |
| Authorization Code | El usuario que autorizó la aplicación desde el navegador. |
Advertencia: si ese usuario se desactiva o pierde el permiso para administrar campañas, la aplicación deja de poder crear, editar o eliminar campañas. Lo mismo ocurre con el alcance para crear contenidos si el usuario pierde el permiso para administrar contenidos.
Catálogos
Los catálogos de la aplicación definen:
- Qué contenido puede utilizar en las campañas que crea o edita, del mismo modo que los catálogos de un usuario administrador.
- En qué catálogos puede guardar los contenidos que crea.
¿Cuándo son obligatorios?
Los catálogos son obligatorios cuando la aplicación tiene el alcance para crear o editar campañas, o para crear contenidos. Para el resto de los alcances no se tienen en cuenta.
Opciones de asignación
- Todos los catálogos: la aplicación puede utilizar el contenido de todos los catálogos de la organización.
- Catálogos seleccionados: la aplicación solo puede utilizar el contenido de los catálogos que seleccione.
En ambos casos, solo cuentan los catálogos que la organización tiene contratados. Si un catálogo deja de estar contratado, deja de aplicar sin necesidad de editar la aplicación.
Reglas que limitan los catálogos
- Solo es posible otorgar los catálogos que tiene asignados el usuario que configura la aplicación.
- La aplicación solo utiliza los catálogos que tiene asignados el usuario por el que actúa: con Client Credentials, quien la registró; con Authorization Code, quien la autorizó.
- Si otro administrador le otorga un catálogo que ese usuario no tiene, la aplicación no lo utiliza, aunque figure otorgado.
- Una aplicación no puede editar una campaña cuyo contenido pertenece a un catálogo que no tiene habilitado.
Nota: si una aplicación no puede utilizar un contenido o editar una campaña, verifique primero los catálogos asignados al usuario por el que actúa la aplicación, y luego los catálogos otorgados a la aplicación.
💡 Mejores prácticas
- Guarde el Client Secret en un gestor de secretos aprobado por su organización y nunca lo incluya en código expuesto del lado del cliente.
- Use Client Credentials para procesos automáticos sin usuario, y Authorization Code cuando cada usuario deba consentir el acceso.
- Otorgue solo los alcances de escritura que la integración necesita. Por ejemplo, evite otorgar el alcance para eliminar campañas si la integración solo las crea.
- Para integraciones con Client Credentials, registre la aplicación con un usuario estable, que no vaya a perder su permiso ni a desactivarse.
- Asigne a la aplicación solo los catálogos que va a utilizar, en lugar de Todos los catálogos, cuando la integración trabaje con un programa puntual.
- Antes de modificar los permisos o catálogos de un administrador, revise si hay aplicaciones registradas que actúan en su nombre.
- Documente internamente qué usuario registró o autorizó cada aplicación y qué alcances tiene.