Saltar al contenido principal

OAuth 2.0 (client credentials)

La API de Energy Management usa el flujo OAuth 2.0 client_credentials. Toda solicitud (excepto GET /health y POST /oauth/token) requiere un token Bearer:

1. Crear credenciales

Cualquier usuario de tu organización puede crear credenciales de cliente OAuth en el panel de RiDERgy: abre Mi cuenta, ve a OAuth Clients y elige Crear cliente. Antes, RiDERgy tiene que activar la API Energy Management para tu organización; sin ella, las solicitudes fallan con 403 FEATURE_NOT_ENABLED.
  • ID de cliente (emcl_...): no es secreto. Sigue visible en el panel.
  • Secreto de cliente (emcs_...): se muestra una sola vez, al crear el cliente. Guárdalo de inmediato en un gestor de contraseñas o almacén de secretos. RiDERgy no puede volver a mostrarlo; si se pierde, crea un cliente nuevo y revoca el anterior.
  • Elige solo los scopes que necesita tu integración. Los clientes nuevos empiezan en solo lectura.
  • Un cliente pertenece a tu organización, no a la persona que lo creó, así que sigue funcionando si esa persona se va.
  • RiDERgy no emite claves API. Las solicitudes con una cabecera x-api-key se rechazan con 401; usa siempre un token Bearer como se describe abajo.
¿Aún sin acceso al panel? Mientras se incorpora tu organización, RiDERgy puede emitir un cliente temporal que caduca a los 7 días. Recibirás el ID de cliente y el secreto por dos canales distintos. En cuanto tengas acceso al panel, crea tu propio cliente y pide a RiDERgy que revoque el temporal.

2. Obtener un token de acceso

Los tokens caducan después de 3600 segundos (1 hora). Solicita uno nuevo antes de que el actual expire. También puedes enviar las credenciales mediante Authorization: Basic base64(client_id:client_secret) con grant_type=client_credentials en el cuerpo (RFC 6749).

3. Usar el token

Envía el token como Authorization: Bearer <token> en cada solicitud:
  • Tu tenant está incorporado en el token y no puede ser falsificado — las credenciales de un tenant no pueden acceder a los datos de otro.
  • Un token caducado o inválido devuelve 401 UNAUTHORIZED.
  • Un token sin el scope requerido devuelve 403 INSUFFICIENT_SCOPE.

Scopes

Los tokens llevan scopes que controlan a qué endpoints se puede acceder: Las solicitudes a endpoints que requieran un scope que el token no tiene fallarán con 403 INSUFFICIENT_SCOPE.

Probar en la documentación

  1. Abre Obtener un token de acceso y haz clic en Try it.
  2. Introduce tu client_id y tu client_secret, deja grant_type como client_credentials y envía la solicitud.
  3. Copia el access_token de la respuesta.
  4. Abre cualquier página de endpoint de la Referencia de la API, pega el token en el campo Authorization y envía la solicitud.
Las solicitudes desde la documentación van a la API de producción y solo llegan a las ubicaciones de tu organización. Un POST/PUT cambia límites de carga reales, así que prueba con un cliente de solo lectura si no quieres aplicar cambios.

Rotar y revocar credenciales

  • Rotar: crea un cliente nuevo, cambia tu integración a él y después revoca el anterior.
  • Revocar: en el panel, junto al cliente. La revocación es inmediata: los tokens ya emitidos para ese cliente dejan de funcionar en la siguiente solicitud.
  • Los clientes temporales caducados dejan de funcionar de la misma forma.