Resumen
El acceso a la API de Hybo se realiza mediante OAuth 2.0 con tokens delegados de usuario: todas las llamadas se ejecutan en nombre de un usuario autenticado de Hybo, y la API aplica exactamente los permisos de ese usuario. No existe acceso anónimo.
Para cada integración, Hybo registra una aplicación dedicada en su proveedor de identidad (Microsoft Entra External ID / B2C) y entrega las credenciales necesarias para obtener tokens. Esa aplicación es la identidad de la integración y el único mecanismo de acceso soportado.
Qué entrega Hybo
Dato | Descripción | Ejemplo de formato |
Client ID | Identificador de la aplicación registrada para el cliente. | 11111111-2222-3333-4444-555555555555 |
Client Secret | Credencial secreta, entregada por canal seguro junto con su fecha de expiración. La renovación debe solicitarla el cliente antes del vencimiento. | xxx~yyyy... |
Authorization URL | Endpoint de autorización del proveedor de identidad de Hybo. | |
Token URL | Endpoint de emisión de tokens. | |
Scope | Permiso delegado que debe solicitarse al pedir el token. | |
URL base de la API | Host contra el que se realizan las llamadas, por entorno. |
Authorization URL, Token URL y Scope son estables y forman parte del contrato de integración. Hybo procurará avisar con antelación (orientativamente 30 días) de cualquier cambio, salvo motivos urgentes de seguridad o del proveedor de identidad.
¿Ya tenéis una política de acceso a medida acordada con Hybo (por ejemplo, federación con vuestro propio proveedor de identidad)? La integración usará esa misma política; el resto del flujo no cambia.
Qué necesitamos recibir de vosotros
Antes de dar de alta la integración, necesitamos que nos facilitéis:
Redirect URI(s) de vuestra plataforma o aplicación. Ejemplos habituales:
Power Automate / Power Apps (custom connector):
https://global.consent.azure-apim.net/redirectPostman (pruebas):
https://oauth.pstmn.io/v1/callbackAplicación propia: la URL de callback de vuestro backend o frontend
Contacto técnico para la entrega de credenciales y avisos (rotación de secretos, cambios de contrato).
Descripción breve del caso de uso: qué herramienta llamará a la API y con qué finalidad, para asignar los permisos adecuados.
Solo funcionarán los Redirect URIs comunicados y registrados. Añadir uno nuevo requiere solicitarlo a Hybo.
Cómo se obtiene y usa el token
El flujo habilitado es OAuth 2.0 Authorization Code (delegado):
Vuestra aplicación redirige al usuario a la Authorization URL, solicitando el Scope proporcionado.
El usuario se autentica en la pantalla de login de Hybo con su cuenta habitual.
El proveedor de identidad devuelve un código de autorización al Redirect URI registrado.
Vuestra aplicación intercambia el código por un access token (y un refresh token) en la Token URL, autenticándose con vuestro Client ID y Client Secret.
Cada llamada a la API incluye el token en la cabecera:
GET /api/Parking/ZonesByContext HTTP/1.1
Host: api.{entorno}.hybo.app
Authorization: Bearer <access_token>
Accept: application/json
La mayoría de plataformas gestionan este flujo automáticamente: en Power Automate se configura una vez en la pestaña Security del custom connector y la conexión se encarga del resto; en aplicaciones propias, librerías estándar como MSAL implementan el flujo completo, incluida la renovación.
Identidad y permisos
El token es del usuario: la API resuelve el tenant, el usuario, sus roles y contextos a partir de los claims del token. Un userId o email enviado en el cuerpo de una petición no sustituye la identidad del token.
La integración solo puede hacer lo que el usuario autenticado puede hacer. No hay elevación de permisos.
El usuario debe existir en Hybo y disponer de los roles correspondientes al módulo utilizado (por ejemplo, AppUser, ParkingAppUser para parking).
Vida del token y renovación
Elemento | Comportamiento |
Access token | Vigencia corta (aprox. 60 minutos). Se envía en cada petición. |
Refresh token | Lo gestiona vuestra plataforma (MSAL, Power Platform, etc.) para renovar el access token sin nueva intervención del usuario. |
Expiración | Una respuesta 401 Unauthorized con un token previamente válido indica normalmente expiración: renovad y reintentad. |
La API no expone endpoints propios de login o refresh; toda la emisión y renovación de tokens se realiza contra el proveedor de identidad.
Integraciones desatendidas (flujos programados, agentes)
Los procesos que se ejecutan sin usuario presente (flujos programados de Power Automate, tareas de un agente, sincronizaciones) utilizan igualmente el modelo delegado: la conexión se crea una vez con un usuario y las ejecuciones posteriores usan su identidad.
Recomendación: crear esas conexiones con una cuenta de servicio dedicada (por ejemplo, [email protected]), dada de alta en Hybo con los permisos estrictamente necesarios, en lugar de la cuenta personal de un empleado. Así la integración no depende del ciclo de vida de ninguna persona (bajas, cambios de contraseña, deshabilitaciones).
El acceso genérico con permisos de aplicación (client credentials / app-only) no forma parte del contrato estándar. Hybo dispone de un contexto de aplicación para un conjunto limitado de endpoints, orientado a integraciones sencillas de consulta o a acciones relacionadas con el check-in. Este mecanismo no se habilita por defecto: si vuestra integración lo necesita, contactad con Hybo para revisar el caso de uso.
Ciclo de vida de las credenciales
El Client Secret caduca (vigencia habitual: 12–24 meses). La fecha de expiración se entrega junto con las credenciales; es responsabilidad del cliente solicitar la renovación con antelación suficiente (recomendado: al menos 15 días antes del vencimiento) para evitar la interrupción de la integración.
La sustitución del secret consiste en actualizar su valor en la configuración de la integración, sin cambios de código.
El secret debe custodiarse de forma segura (gestor de secretos o configuración protegida de la plataforma). No debe incluirse en código fuente, repositorios ni comunicaciones en claro.
En caso de sospecha de compromiso del secret, contactad con Hybo inmediatamente para su revocación y reemisión.
Hybo puede deshabilitar la aplicación de un cliente al finalizar la relación contractual o ante un uso indebido, con efecto inmediato sobre el acceso.
Política de soporte
El único mecanismo de acceso soportado es la aplicación registrada entregada por Hybo, mediante el flujo OAuth descrito en este artículo. Las integraciones basadas en la reutilización de tokens de sesión de las aplicaciones de Hybo, u otros mecanismos no descritos aquí, no están soportadas y pueden dejar de funcionar en cualquier momento sin previo aviso.
El acceso se encuentra en fase beta: la superficie de API disponible y sus condiciones pueden evolucionar. Hybo procurará avisar con antelación suficiente (orientativamente 30 días) de los cambios que afecten a integraciones existentes, salvo motivos urgentes de seguridad o del proveedor de identidad.
Errores frecuentes en la puesta en marcha
Síntoma | Causa habitual | Solución |
redirect_uri mismatch durante el login | El Redirect URI usado no coincide con el registrado. | Verificad la URI exacta y solicitad su alta a Hybo si falta. |
AADB2C90205 o error de scope inválido | Scope mal escrito o incompleto. | Usad el valor de Scope exactamente como se entregó. |
401 Unauthorized en todas las llamadas con login correcto | El token no incluye la audiencia esperada. | Incluid el Scope de Hybo en la solicitud de autorización, no solo en la de token. |
401 tras funcionar un tiempo | Access token expirado y renovación no configurada. | Comprobad la gestión del refresh token en vuestra plataforma. |
403 Forbidden con token válido | El usuario no tiene el rol o contexto necesario en Hybo. | Revisad los roles del usuario (p. ej. ParkingAppUser) con el administrador de Hybo. |
El flujo funciona y deja de hacerlo semanas después | Secret expirado sin solicitar renovación, o cuenta del creador de la conexión deshabilitada. | Solicitad a Hybo un nuevo secret o recread la conexión con la cuenta de servicio. |
Checklist de alta
El cliente envía a Hybo:
Redirect URI(s) de vuestra plataforma
Contacto técnico
Descripción del caso de uso y herramienta
Hybo entrega al cliente:
Client ID
Client Secret (canal seguro) con su fecha de expiración
Authorization URL y Token URL
Scope
URL base de la API por entorno
Usuario y datos de prueba, si aplica
Verificación conjunta:
Login completado desde vuestra plataforma
Primera llamada autenticada con respuesta 200
Para cualquier duda durante la integración, contactad con vuestro equipo de referencia en Hybo.