Saltar al contenido principal

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.
HostRol
console.rhombussystems.comDonde el usuario inicia sesión y aprueba tu aplicación
auth.rhombussystems.comEndpoint de intercambio de tokens
api2.rhombussystems.comLlamadas 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>/callback para 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 par clientId 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.
Las aplicaciones OAuth de producción requieren revisión de Rhombus. Puedes auto-registrar un clientId con la llamada a la API mostrada abajo para desarrollo local y pruebas, pero no distribuyas aplicaciones a usuarios finales con un clientId auto-registrado: Rhombus puede aplicar limitación de tasa o revocar el uso en producción no revisado. Inicia una revisión tan pronto como tu prototipo funcione.

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.
import requests

headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.post(
    "https://api2.rhombussystems.com/api/oauth/submitApplication",
    headers=headers,
    json={
        "name": "Acme Console",
        "description": "Acme internal dashboard for Rhombus operators",
        "contactEmail": "engineering@acme.example",
        "redirectUri": "https://acme.example/oauth/callback",
    },
)

data = response.json()
print("clientId:    ", data["clientId"])
print("clientSecret:", data["clientSecret"])  # store securely — not retrievable later
Ejemplo de respuesta:
{
  "clientId": "PJjjlcKAQPCzIcaeprzEVg",
  "clientSecret": "kixFP1l8c55dDt0WdeX8BNwUlnFknGTr9qdn3AYKpsM"
}
Hay endpoints adicionales disponibles para gestionar aplicaciones registradas: getAllApplicationsForOrg, getApplicationByClientId, updateApplication y deleteApplication. Consulta la Referencia de la API bajo la etiqueta OAuth.

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
Conserva el 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.
import base64
import hashlib
import secrets
from urllib.parse import urlencode

def new_pkce_pair():
    verifier = secrets.token_urlsafe(64)  # 86 chars after base64
    digest = hashlib.sha256(verifier.encode("ascii")).digest()
    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
    return verifier, challenge

client_id    = "PJjjlcKAQPCzIcaeprzEVg"
redirect_uri = "https://acme.example/oauth/callback"

code_verifier, code_challenge = new_pkce_pair()
state = secrets.token_urlsafe(32)

# Save code_verifier + state in the user's session before redirecting.

params = {
    "type":      "oauth",
    "client_id": client_id,
    "redirect":  redirect_uri,
    "state":     state,
    "challenge": code_challenge,
}
authorize_url = f"https://console.rhombussystems.com/login?{urlencode(params)}"
print(authorize_url)
Ten en cuenta que la URL de autorización utiliza los nombres de parámetros client_id, redirect, state y challenge: estos difieren ligeramente de los nombres estándar de OAuth (redirect_uri, code_challenge). Usa exactamente los nombres mostrados arriba.
Redirige el navegador del usuario a la URL que construiste. El usuario iniciará sesión en Rhombus y aprobará tu aplicación.

Paso 3: Maneja el callback de redirección

Después de que el usuario se autentica, Rhombus redirige a tu redirectUri con parámetros de consulta:
ParámetroDescripción
codeCódigo de autorización para intercambiar por un access token. De corta duración.
stateEl 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.
errorPresente en caso de fallo (p. ej., access_denied).
error_descriptionDetalle del error legible para humanos.
Verifica siempre que el parámetro state coincida con lo que enviaste. Una falta de coincidencia indica un posible ataque CSRF: aborta el flujo.
from flask import Flask, request, session, abort

app = Flask(__name__)

@app.route("/oauth/callback")
def callback():
    if request.args.get("error"):
        return f"Login failed: {request.args['error_description']}", 400

    code  = request.args.get("code")
    state = request.args.get("state")
    is_partner = request.args.get("isPartner") == "true"

    if state != session.pop("oauth_state", None):
        abort(400, "state mismatch")

    code_verifier = session.pop("oauth_verifier", None)
    # Proceed to Step 4 — exchange `code` for an access token.
    ...

Paso 4: Intercambia el código por un access token

Llama a POST 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.
import requests

token_response = requests.post(
    "https://auth.rhombussystems.com/oauth/token",
    headers={
        "Content-Type": "application/json",
        "x-auth-scheme": "web2",
    },
    json={
        "grantType":         "AUTHORIZATION_CODE",
        "authorizationCode": code,
        "clientId":          client_id,
        "clientSecret":      client_secret,
        "redirectUri":       redirect_uri,
        "codeVerifier":      code_verifier,
        "codeChallengeType": "S256",
    },
)
token_response.raise_for_status()
tokens = token_response.json()

access_token  = tokens["accessToken"]
refresh_token = tokens["refreshToken"]
expires_in_s  = tokens["accessTokenExpirationSec"]
Ejemplo de respuesta:
{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "def50200...",
  "accessTokenExpirationSec": 3600
}

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-token
  • x-auth-access-token: <accessToken>
Esto es distinto del esquema estándar de API key (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.
import requests

headers = {
    "x-auth-scheme": "api-oauth-token",
    "x-auth-access-token": access_token,
    "Content-Type": "application/json",
}

response = requests.post(
    "https://api2.rhombussystems.com/api/user/getUsersInOrg",
    headers=headers,
    json={},
)

users = response.json().get("users", [])
for user in users:
    print(user.get("email"), "—", user.get("name"))
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 campo accessTokenExpirationSec 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 hace rhombus 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>:
import requests

response = requests.post(
    "https://api2.rhombussystems.com/api/integrations/org/submitApiTokenApplication",
    headers={
        "x-auth-scheme": "api-oauth-token",
        "x-auth-access-token": access_token,
        "Content-Type": "application/json",
    },
    json={
        "displayName": "Acme Console — background worker",
        "authType": "API_TOKEN",
    },
)

data = response.json()
api_key = data["apiKey"]  # store this securely — treat it like a password
A partir de ese punto, usa la API key con los headers estándar 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.
Trata las API keys emitidas como contraseñas. Son de larga duración y otorgan los mismos permisos que el usuario que las creó. Almacénalas cifradas en reposo, nunca en el control de versiones, y rota o elimina las claves no utilizadas.

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 incluye isPartner=true. Cuando isPartner es true:
  • Usa x-auth-scheme: partner-api-oauth-token en lugar de api-oauth-token en las llamadas a la API
  • Emite claves de larga duración mediante POST /api/partner/submitApiTokenApplication en 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

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.
Causas comunes:
  • redirectUri no coincide: el redirectUri en el cuerpo del intercambio de tokens debe coincidir exactamente (incluyendo esquema, host, puerto y ruta) con el redirect que enviaste en el Paso 2 y la URI registrada con tu aplicación OAuth.
  • code expirado: los códigos de autorización son de corta duración (segundos, no minutos). Intercámbialos inmediatamente en el callback.
  • codeVerifier no genera el hash de codeChallenge: 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, no api-token ni api-oauth-token.
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.
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.
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
Last modified on April 30, 2026