Documentation Index
Fetch the complete documentation index at: https://api-docs.rhombus.community/llms.txt
Use this file to discover all available pages before exploring further.
Esta página fue traducida automáticamente. Si encuentra errores o tiene sugerencias, contáctenos.
Descripción general
Rhombus soporta OAuth 2.0 con PKCE para que puedas crear aplicaciones que inicien sesión con las credenciales existentes de Rhombus. Cuando un usuario hace clic en Iniciar sesión con Rhombus en tu aplicación, es redirigido a la Consola de Rhombus para autenticarse, y luego es devuelto a tu URI de redirección con un código de autorización de corta duración. Intercambias ese código por un access token y llamas a la API de Rhombus en nombre del usuario. Este es el mismo flujo utilizado por el Rhombus CLI oficial:rhombus login es una implementación de referencia funcional en Go que puedes leer de principio a fin.
Usa esta guía para construir:
- Herramientas CLI que se autentican mediante inicio de sesión por navegador (como el propio Rhombus CLI)
- Aplicaciones web que permiten a los usuarios de Rhombus iniciar sesión en tu servicio
- Paneles de administración e integraciones internas para clientes que gestionan muchas organizaciones de Rhombus
- Aplicaciones de escritorio usando una redirección por loopback local
Lo que esta guía no es. Esta guía es para desarrolladores externos que crean aplicaciones que inician sesión a usuarios de Rhombus. Si eres un cliente de Rhombus que intenta configurar SAML SSO para tus empleados (Okta, Azure AD, Google Workspace) o SCIM para el aprovisionamiento de usuarios, consulta Aprovisionamiento SAML SSO y SCIM en su lugar: esa es una superficie distinta del flujo OAuth descrito aquí.
Cómo funciona el flujo
La superficie OAuth de Rhombus abarca tres hosts. Esta es una fuente común de confusión: tu aplicación se comunica con los tres en distintas etapas del flujo.| Host | Rol |
|---|---|
console.rhombussystems.com | Donde el usuario inicia sesión y aprueba tu aplicación |
auth.rhombussystems.com | Endpoint de intercambio de tokens |
api2.rhombussystems.com | Llamadas a la API realizadas con el access token resultante |
Antes de comenzar
Antes de comenzar, asegúrate de tener:
- Una cuenta de Rhombus con una API key (generada en la Consola de Rhombus en Settings → API Management)
- Una URI de redirección que tu aplicación controle: una URL HTTPS pública en producción, o
http://localhost:<port>/callbackpara aplicaciones CLI y de escritorio - Familiaridad básica con el flujo de código de autorización OAuth 2.0 y PKCE (RFC 7636)
Paso 1: Registra tu aplicación
Antes de poder iniciar un flujo OAuth, Rhombus necesita conocer tu aplicación. El registro te entrega un parclientId y clientSecret.
Hay dos rutas para obtener un clientId, dependiendo de la etapa de tu desarrollo:
Prototipado y desarrollo
Llama a la API
submitApplication directamente con tu API key existente. Es la ruta más rápida hacia un flujo funcional en localhost. Autoservicio, inmediato.Producción y distribución
Las aplicaciones que se entregarán a clientes o aceptarán inicios de sesión de usuarios fuera de tu propia organización deben ser revisadas por Rhombus. Contacta a tu representante de Rhombus o publica en la Comunidad de Desarrolladores para iniciar la revisión.
Registrarse con la API
POST /api/oauth/submitApplication devuelve un clientId y clientSecret nuevos. Almacena el clientSecret de forma segura: no se puede recuperar más tarde.
Paso 2: Construye la URL de autorización
Rhombus usa PKCE (Proof Key for Code Exchange) para protegerse contra la interceptación de códigos de autorización. Para cada intento de inicio de sesión, genera:- Un code verifier: una cadena aleatoria URL-safe de 43 a 128 caracteres
- Un code challenge: el hash SHA-256 del verifier, codificado en base64url (sin padding)
- Un parámetro state: un valor aleatorio impredecible utilizado para prevenir CSRF
codeVerifier y el state junto con la sesión del usuario (o, para herramientas CLI, en memoria del proceso) hasta que llegue el callback. Necesitarás ambos.
Paso 3: Maneja el callback de redirección
Después de que el usuario se autentica, Rhombus redirige a turedirectUri con parámetros de consulta:
| Parámetro | Descripción |
|---|---|
code | Código de autorización para intercambiar por un access token. De corta duración. |
state | El valor de state que enviaste — debes verificar que coincida. |
isPartner | "true" si el usuario autenticado es titular de una cuenta partner. Consulta cuentas partner. |
accessToken | (a veces presente) Un access token pre-intercambiado. Si está presente, omite el paso de intercambio de tokens y úsalo directamente. |
error | Presente en caso de fallo (p. ej., access_denied). |
error_description | Detalle del error legible para humanos. |
Paso 4: Intercambia el código por un access token
Llama aPOST https://auth.rhombussystems.com/oauth/token con el código de autorización y tu verifier PKCE. Este es un host distinto del de la API principal: el endpoint /oauth/token reside en auth.rhombussystems.com.
Paso 5: Llama a la API de Rhombus
Usa el access token con dos headers en cada llamada a la API de Rhombus:x-auth-scheme: api-oauth-tokenx-auth-access-token: <accessToken>
api-token + x-auth-apikey): los access tokens OAuth utilizan su propio identificador de esquema para que Rhombus pueda aplicar autorización específica de OAuth.
Si esta llamada devuelve una lista de usuarios, tu flujo OAuth funciona de extremo a extremo. El usuario se autenticó, tienes un access token y estás llamando a la API en su nombre.
Tiempo de vida del access token
El campoaccessTokenExpirationSec en la respuesta de tokens te indica cuánto tiempo es válido el access token (típicamente una hora). Cuando expira, la API de Rhombus devolverá un error de autenticación.
Para acceso de larga duración —servicios en segundo plano, daemons, trabajos programados o cualquier cliente que no pueda volver a solicitar al usuario— emite una API key duradera usando el access token OAuth (consulta la siguiente sección) en lugar de intentar mantener una sesión OAuth refrescada. Este es el patrón que utiliza el Rhombus CLI.
Se devuelve un
refreshToken junto con el access token. El flujo de refresco no forma parte actualmente de la superficie soportada públicamente: para acceso persistente, prefiere la ruta de API key descrita abajo.Emite una API key de larga duración
Una vez que un usuario ha iniciado sesión con OAuth, puedes intercambiar el access token de corta duración por una API key permanente. Esto es lo que hacerhombus login para que el CLI pueda continuar realizando llamadas a la API después de que la sesión del navegador termine.
Llama a POST /api/integrations/org/submitApiTokenApplication con x-auth-scheme: api-oauth-token y x-auth-access-token: <accessToken>:
x-auth-scheme: api-token + x-auth-apikey: no se requieren más llamadas OAuth. El CLI también soporta una variante basada en certificado (mTLS) de este flujo para implementaciones con mayor seguridad; consulta cmd/login.go para la implementación completa.
Trabajar con cuentas partner
Si el usuario que se autentica es titular de una cuenta partner (un MSP o revendedor que gestiona varias organizaciones de clientes), el callback incluyeisPartner=true.
Cuando isPartner es true:
- Usa
x-auth-scheme: partner-api-oauth-tokenen lugar deapi-oauth-tokenen las llamadas a la API - Emite claves de larga duración mediante
POST /api/partner/submitApiTokenApplicationen lugar del endpoint estándar de integraciones - Para actuar sobre una organización cliente específica, incluye el UUID de la organización cliente en el campo de solicitud apropiado (consulta Endpoints partner en la Referencia de la API)
Las cuentas partner son relativamente raras en aplicaciones de terceros. Si tu aplicación apunta a clientes finales con organizaciones estándar de Rhombus, puedes tratar con seguridad
isPartner=false como la ruta predeterminada y mostrar un error claro si una cuenta partner intenta iniciar sesión cuando no la soportas.Implementación de referencia
El Rhombus CLI es una referencia de producción para todo lo de esta guía.cmd/login.go recorre todo el flujo de extremo a extremo: generación de PKCE, servidor de callback local, construcción de la URL de autorización, intercambio de tokens, ramificación partner, emisión de API key con mTLS y persistencia de credenciales.
Si algo en tu implementación no funciona, compara tu comportamiento contra el CLI: es el ejemplo canónico.
Solución de problemas
state no coincide en el callback
state no coincide en el callback
Tu callback recibió un valor de
state distinto al que enviaste. Verifica que estás conservando el state que generaste en el Paso 2 junto con la sesión del usuario (o en memoria para herramientas CLI) y comparándolo en el callback. Una falta de coincidencia persistente puede indicar un intento de CSRF: aborta el flujo en lugar de reintentar silenciosamente.El intercambio de tokens devuelve HTTP 400 o `error: true`
El intercambio de tokens devuelve HTTP 400 o `error: true`
Causas comunes:
redirectUrino coincide: elredirectUrien el cuerpo del intercambio de tokens debe coincidir exactamente (incluyendo esquema, host, puerto y ruta) con elredirectque enviaste en el Paso 2 y la URI registrada con tu aplicación OAuth.codeexpirado: los códigos de autorización son de corta duración (segundos, no minutos). Intercámbialos inmediatamente en el callback.codeVerifierno genera el hash decodeChallenge: verifica que estás usando SHA-256 y codificación base64url sin padding=tanto en la generación del challenge como en la transmisión del verifier.- Header incorrecto: el intercambio de tokens requiere
x-auth-scheme: web2, noapi-tokenniapi-oauth-token.
Las llamadas a la API devuelven 401 con un access token válido
Las llamadas a la API devuelven 401 con un access token válido
Revisa los headers. Los access tokens OAuth usan
x-auth-scheme: api-oauth-token y x-auth-access-token: <token>. Usar x-auth-apikey (el header de API key) con un access token OAuth fallará: son esquemas distintos con nombres de header distintos.La redirección termina en la página de inicio de sesión de la consola otra vez sin código
La redirección termina en la página de inicio de sesión de la consola otra vez sin código
El
client_id que estás enviando puede no ser reconocido. Verifica que estás usando el clientId devuelto por submitApplication, no el UUID de aplicación de una respuesta diferente. Si rotaste aplicaciones, el clientId antiguo ya no es válido.Llega `isPartner=true` inesperadamente
Llega `isPartner=true` inesperadamente
Un titular de cuenta partner se autenticó a través de un flujo que tu aplicación no soporta. Implementa el flujo partner o muestra al usuario un mensaje de error claro explicando que tu aplicación solo soporta organizaciones estándar de Rhombus.
Próximos pasos
Rhombus CLI
Lee cómo el CLI oficial usa este flujo de extremo a extremo
Referencia de la API
Navega todos los endpoints disponibles una vez que tengas un access token
Límites de tasa
Comprende los límites de solicitudes antes de lanzar
Comunidad de desarrolladores
Solicita revisión de OAuth de producción y haz preguntas