Iniciar sesión con Rhombus

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

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.

Antes de comenzar

Paso 1: Registra tu aplicación

Antes de poder iniciar un flujo OAuth, Rhombus necesita conocer tu aplicación. El registro te entrega un clientId y, para un cliente confidencial, un clientSecret. Un cliente público (una CLI o una app de escritorio que no puede guardar un secreto) se registra con tokenEndpointAuthMethod: "none" y no recibe ningún secreto.

Hay dos formas de obtener un clientId:

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

const response = await fetch(
  "https://api2.rhombussystems.com/api/oauth/submitApplication",
  {
    method: "POST",
    headers: {
      "x-auth-scheme": "api-token",
      "x-auth-apikey": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Acme Console",
      description: "Acme internal dashboard for Rhombus operators",
      contactEmail: "engineering@acme.example",
      redirectUri: "https://acme.example/oauth/callback",
    }),
  }
);

const { clientId, clientSecret } = await response.json();
console.log("clientId:    ", clientId);
await saveToSecretsManager("rhombus-oauth-client-secret", clientSecret); // shown only once; never log it

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]string{
        "name":         "Acme Console",
        "description":  "Acme internal dashboard for Rhombus operators",
        "contactEmail": "engineering@acme.example",
        "redirectUri":  "https://acme.example/oauth/callback",
    })

    req, _ := http.NewRequest("POST",
        "https://api2.rhombussystems.com/api/oauth/submitApplication",
        bytes.NewReader(body))
    req.Header.Set("x-auth-scheme", "api-token")
    req.Header.Set("x-auth-apikey", "YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result struct {
        ClientID     string `json:"clientId"`
        ClientSecret string `json:"clientSecret"`
    }
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println("clientId:    ", result.ClientID)
    fmt.Println("clientSecret:", result.ClientSecret) // store securely
}

Ejemplo de respuesta:

{
  "clientId": "PJjjlcKAQPCzIcaeprzEVg",
  "clientSecret": "YOUR_CLIENT_SECRET"
}

Registro dinámico de clientes

Una aplicación también puede registrarse sola con el registro dinámico de clientes de OAuth 2.0 (RFC 7591): envía un cuerpo JSON a https://auth-web.rhombussystems.com/oauth/register, sin clave de API. Registra un cliente público ("token_endpoint_auth_method": "none") cuando la aplicación no pueda guardar un secreto; en ese caso depende solo de PKCE.

curl -X POST "https://auth-web.rhombussystems.com/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme CLI",
    "redirect_uris": ["http://localhost:8765/callback"],
    "token_endpoint_auth_method": "none"
  }'

La respuesta incluye el nuevo client_id, y un client_secret salvo que hayas registrado un cliente público. Guarda el client_id y reutilízalo en los siguientes inicios de sesión en lugar de registrarte de nuevo.

El registro anónimo está limitado a 10 registros por hora desde una misma dirección IP de cliente y a 100 por hora en total. Si se supera cualquiera de los dos límites, el endpoint devuelve 429 Too Many Requests con un encabezado Retry-After y un cuerpo de error de OAuth cuyo error es temporarily_unavailable; espera los segundos que indica Retry-After antes de volver a intentarlo.

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.

Indica en scope el acceso que necesita tu aplicación, separado por espacios (consulta Scopes). Los ejemplos solicitan los tres scopes porque más adelante esta guía emite una clave de API; una aplicación que solo lee solicita scope=read.

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 = {
    "client_id":             client_id,
    "redirect_uri":          redirect_uri,
    "response_type":         "code",
    "scope":                 "read write physical",
    "state":                 state,
    "code_challenge":        code_challenge,
    "code_challenge_method": "S256",
}
authorize_url = f"https://console.rhombussystems.com/oauth/authorize?{urlencode(params)}"
print(authorize_url)

import crypto from "node:crypto";

function newPkcePair() {
  const verifier = crypto.randomBytes(64).toString("base64url");
  const challenge = crypto
    .createHash("sha256")
    .update(verifier)
    .digest("base64url");
  return { verifier, challenge };
}

const clientId    = "PJjjlcKAQPCzIcaeprzEVg";
const redirectUri = "https://acme.example/oauth/callback";

const { verifier: codeVerifier, challenge: codeChallenge } = newPkcePair();
const state = crypto.randomBytes(32).toString("base64url");

// Save codeVerifier + state in the user's session before redirecting.

const params = new URLSearchParams({
  client_id: clientId,
  redirect_uri: redirectUri,
  response_type: "code",
  scope: "read write physical",
  state,
  code_challenge: codeChallenge,
  code_challenge_method: "S256",
});
const authorizeUrl = `https://console.rhombussystems.com/oauth/authorize?${params}`;
console.log(authorizeUrl);

package main

import (
    "crypto/rand"
    "crypto/sha256"
    "encoding/base64"
    "fmt"
    "net/url"
)

func newPkcePair() (verifier, challenge string) {
    b := make([]byte, 64)
    rand.Read(b)
    verifier = base64.RawURLEncoding.EncodeToString(b)
    sum := sha256.Sum256([]byte(verifier))
    challenge = base64.RawURLEncoding.EncodeToString(sum[:])
    return
}

func randomState() string {
    b := make([]byte, 32)
    rand.Read(b)
    return base64.RawURLEncoding.EncodeToString(b)
}

func main() {
    clientID    := "PJjjlcKAQPCzIcaeprzEVg"
    redirectURI := "https://acme.example/oauth/callback"

    codeVerifier, codeChallenge := newPkcePair()
    state := randomState()

    // Save codeVerifier + state in the user's session before redirecting.

    params := url.Values{
        "client_id":             {clientID},
        "redirect_uri":          {redirectURI},
        "response_type":         {"code"},
        "scope":                 {"read write physical"},
        "state":                 {state},
        "code_challenge":        {codeChallenge},
        "code_challenge_method": {"S256"},
    }
    fmt.Println("https://console.rhombussystems.com/oauth/authorize?" + params.Encode())
}

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:

En caso de éxito, el callback incluye:

En caso de fallo, el callback incluye error (p. ej., access_denied) y error_description (detalle legible para humanos) en lugar de code.

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")

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

import express from "express";
const app = express();

app.get("/oauth/callback", (req, res) => {
  const { code, state, error, error_description } = req.query;

  if (error) return res.status(400).send(`Login failed: ${error_description}`);
  if (state !== req.session.oauthState) return res.status(400).send("state mismatch");

  const codeVerifier = req.session.oauthVerifier;
  // Proceed to Step 4 — exchange `code` for an access token.
});

// HTTP handler for your redirect URI.
func handleCallback(w http.ResponseWriter, r *http.Request) {
    q := r.URL.Query()

    if errMsg := q.Get("error"); errMsg != "" {
        http.Error(w, "login failed: "+q.Get("error_description"), 400)
        return
    }

    code := q.Get("code")
    state := q.Get("state")

    if state != session.State(r) {
        http.Error(w, "state mismatch", 400)
        return
    }

    codeVerifier := session.Verifier(r)
    // Proceed to Step 4 — exchange `code` for an access token.
    _, _ = code, codeVerifier
}

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

Llama a POST https://auth-web.rhombussystems.com/oauth/token con el código de autorización y tu verifier PKCE. Esta es una solicitud de token OAuth 2.0 estándar: envía los parámetros codificados en formulario (application/x-www-form-urlencoded), no como JSON, y autentica tu cliente con su clientId/clientSecret, ya sea mediante HTTP Basic auth (client_secret_basic) o en el cuerpo de la solicitud (client_secret_post, mostrado abajo). Un cliente público (registrado con token_endpoint_auth_method none) no tiene secreto y envía solo client_id. Este es un host distinto del de la API principal: el endpoint /oauth/token reside en auth-web.rhombussystems.com.

import requests

token_response = requests.post(
    "https://auth-web.rhombussystems.com/oauth/token",
    headers={"Content-Type": "application/x-www-form-urlencoded"},
    data={
        "grant_type":    "authorization_code",
        "code":          code,
        "redirect_uri":  redirect_uri,
        "code_verifier": code_verifier,
        "client_id":     client_id,
        "client_secret": client_secret,
    },
)
token_response.raise_for_status()
tokens = token_response.json()

access_token  = tokens["access_token"]
refresh_token = tokens["refresh_token"]
expires_in_s  = tokens["expires_in"]
granted_scope = tokens["scope"]

const tokenResponse = await fetch("https://auth-web.rhombussystems.com/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code,
    redirect_uri: redirectUri,
    code_verifier: codeVerifier,
    client_id: clientId,
    client_secret: clientSecret,
  }),
});

if (!tokenResponse.ok) {
  throw new Error(`Token exchange failed: ${await tokenResponse.text()}`);
}

const {
  access_token: accessToken,
  refresh_token: refreshToken,
  expires_in: expiresIn,
  scope: grantedScope,
} = await tokenResponse.json();

form := url.Values{
    "grant_type":    {"authorization_code"},
    "code":          {code},
    "redirect_uri":  {redirectURI},
    "code_verifier": {codeVerifier},
    "client_id":     {clientID},
    "client_secret": {clientSecret},
}

req, _ := http.NewRequest("POST",
    "https://auth-web.rhombussystems.com/oauth/token",
    strings.NewReader(form.Encode()))
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

resp, err := http.DefaultClient.Do(req)
if err != nil || resp.StatusCode != 200 {
    return fmt.Errorf("token exchange failed")
}
defer resp.Body.Close()

var tokens struct {
    AccessToken  string `json:"access_token"`
    RefreshToken string `json:"refresh_token"`
    TokenType    string `json:"token_type"`
    ExpiresIn    int    `json:"expires_in"`
    Scope        string `json:"scope"`
}
json.NewDecoder(resp.Body).Decode(&tokens)

Ejemplo de respuesta:

{
  "access_token": "AAAAAAAAAAAAAAAAAAAAAA",
  "refresh_token": "BBBBBBBBBBBBBBBBBBBBBB",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write physical"
}

scope lista los scopes que tiene el token, separados por espacios.

Paso 5: Llama a la API de Rhombus

Envía el access token en el encabezado estándar en cada llamada a la API de Rhombus:

• Authorization: Bearer <accessToken>

Un token Bearer sin encabezado x-auth-scheme se interpreta como un access token OAuth, y Authorization: Bearer no transporta ningún otro tipo de credencial. El mismo encabezado funciona en la API REST (api2), en los hosts de medios y en el handshake del WebSocket de eventos. También se acepta el par de encabezados equivalente x-auth-scheme: api-oauth-token y x-auth-access-token: <accessToken>.

import requests

headers = {
    "Authorization": f"Bearer {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"))

const response = await fetch(
  "https://api2.rhombussystems.com/api/user/getUsersInOrg",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}),
  }
);

const { users = [] } = await response.json();
for (const user of users) {
  console.log(`${user.email} — ${user.name}`);
}

req, _ := http.NewRequest("POST",
    "https://api2.rhombussystems.com/api/user/getUsersInOrg",
    strings.NewReader("{}"))
req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
// ... decode response

Scopes

Un scope limita lo que puede hacer un access token. Solicita los scopes en el parámetro scope de la URL de autorización, separados por espacios (por ejemplo, scope=read%20write). Los valores que Rhombus no reconoce se ignoran, y una solicitud sin scope recibe los tres. La pantalla de consentimiento lista los scopes que pide tu aplicación:

La página de cada operación en la referencia de la API muestra el scope que necesita.

• Los scopes nunca añaden acceso. Un token solo puede hacer lo que permiten a la vez el rol del usuario y sus scopes (consulta Scopes de OAuth).
• El WebSocket de eventos necesita read. Un token sin ese scope se rechaza en el handshake.
• El audio de intercomunicación se comprueba en cada mensaje. Enviar audio sin physical cierra el socket con el código 1008.
• Crear, rotar y renovar claves de API requiere los tres scopes (consulta Emite una API key de larga duración).
• Las respuestas de tokens incluyen scope, los scopes que tiene el token. El documento de descubrimiento del servidor de autorización (https://auth-web.rhombussystems.com/.well-known/oauth-authorization-server) y el documento de recurso protegido de la API (https://api2.rhombussystems.com/.well-known/oauth-protected-resource) listan los scopes admitidos en scopes_supported.

Una llamada que necesita un scope que el token no tiene devuelve 403 con errorCode PERMISSION_REQUIRED y un encabezado que indica el scope necesario:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="physical"

Para obtener el scope que falta, vuelve a llevar al usuario por el flujo de autorización con ese scope añadido a scope.

Tiempo de vida del access token

El campo expires_in en la respuesta de tokens te indica cuánto tiempo (en segundos) es válido el access token (típicamente una hora). Cuando expira, la API de Rhombus devuelve 401 con errorCode CREDENTIAL_EXPIRED; refréscalo.

Un cliente que guarda el refresh token mantiene el acceso mientras siga refrescando; la CLI de Rhombus funciona así. Un servicio en segundo plano, un daemon o un trabajo programado que no deba depender del inicio de sesión de un usuario puede, en cambio, emitir una clave de API con el access token (consulta Emite una API key de larga duración).

Refresh tokens

Intercambia el refresh token por un nuevo access token en el mismo endpoint /oauth/token, codificado como formulario:

curl -X POST "https://auth-web.rhombussystems.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN" \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET"   # solo clientes confidenciales

• Los clientes públicos (registrados con token_endpoint_auth_method none, protegidos solo por PKCE) envían solo client_id. Los clientes confidenciales envían también client_secret, en el cuerpo o con HTTP Basic auth.
• Cada refresh rota el refresh token. La respuesta incluye un nuevo refresh_token; guárdalo, porque el que enviaste deja de funcionar.
• Nunca reutilices un refresh token reemplazado. Dentro de los 30 segundos posteriores a su reemplazo se rechaza. Pasados 30 segundos, presentarlo revoca toda la autorización, incluidas las claves de API emitidas con ella, y el usuario tiene que volver a iniciar sesión. Si varios procesos comparten una misma sesión, deja que solo uno de ellos refresque.
• Un refresh token sin usar durante 90 días expira.
• Un refresh fallido devuelve 400 con el error de OAuth invalid_grant: el refresh token se reemplazó, expiró o se revocó. Vuelve a llevar al usuario por el flujo de inicio de sesión.

Los access tokens y los refresh tokens son cadenas opacas, no JWT.

Revocar una autorización

Para terminar una autorización, envía el refresh token a https://auth-web.rhombussystems.com/oauth/token/revoke, codificado como formulario, con token, client_id y, en un cliente confidencial, client_secret. Revocar una autorización:

• Detiene sus tokens en un plazo de 60 segundos en todos los hosts. Las conexiones abiertas al WebSocket de eventos reciben un frame STOMP ERROR y se cierran con el código 1008; los sockets de medios abiertos (video en vivo, intercomunicación, robot, PTZ) se cierran con el código 1008.
• Elimina las claves de API emitidas con esa autorización.
• Termina los tokens federados emitidos con esa autorización.

Eliminar la aplicación revoca todas sus autorizaciones. Consulta también Permisos y rotación de claves.

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 clave de API de larga duración, para un servicio que siga llamando a la API sin la sesión del usuario.

Llama a POST /api/integrations/org/submitApiTokenApplication con Authorization: Bearer <accessToken>. El token necesita los tres scopes (read, write y physical). El cuerpo indica el rol de la nueva clave en permissionGroupUuid: el rol del propio usuario, o uno que tenga permitido asignar. Lista los roles con getPermissionGroups y los roles asignables del usuario con getPermissionsForCurrentUser. Para que la clave caduque, añade expiresAtMs (milisegundos desde epoch). Algunos rechazos, como un rol que el usuario no puede asignar, devuelven HTTP 200 con "error": true y un errorMsg, así que revisa el cuerpo además del código de estado.

import requests

response = requests.post(
    "https://api2.rhombussystems.com/api/integrations/org/submitApiTokenApplication",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={
        "displayName": "Acme Console — background worker",
        "permissionGroupUuid": role_uuid,
        "authType": "API_TOKEN",
    },
)

data = response.json()
if data.get("error"):
    raise RuntimeError(data.get("errorMsg"))
api_key = data["apiKey"]  # store this securely — treat it like a password

const response = await fetch(
  "https://api2.rhombussystems.com/api/integrations/org/submitApiTokenApplication",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      displayName: "Acme Console — background worker",
      permissionGroupUuid: roleUuid,
      authType: "API_TOKEN",
    }),
  }
);

const data = await response.json();
if (data.error) throw new Error(data.errorMsg);
const { apiKey } = data; // store apiKey securely — treat it like a password

body, _ := json.Marshal(map[string]string{
    "displayName":         "Acme Console — background worker",
    "permissionGroupUuid": roleUuid,
    "authType":            "API_TOKEN",
})

req, _ := http.NewRequest("POST",
    "https://api2.rhombussystems.com/api/integrations/org/submitApiTokenApplication",
    bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("Content-Type", "application/json")
// ... execute and decode; store apiKey securely.

A partir de ese punto, usa la clave de API con los encabezados estándar x-auth-scheme: api-token + x-auth-apikey: no se requieren más llamadas OAuth. Para una clave de certificado (mTLS), envía "authType": "CERT" con un csr cuya firma sea válida; consulta Claves de API y certificados. El mismo access token puede rotar una clave (POST /api/integrations/org/rotateApiToken) o renovar el certificado de una clave de certificado (POST /api/integrations/org/renewApiTokenCert), con los mismos tres scopes; consulta Gestionar claves con la API.

Trabajar con cuentas partner

Los usuarios de una organización partner (MSP o revendedor) pueden completar el mismo flujo de "Iniciar sesión con Rhombus", y su access token va en el mismo encabezado Authorization: Bearer <accessToken>. (x-auth-scheme: partner-api-oauth-token con x-auth-access-token se acepta como alias.)

Para actuar dentro de una organización cliente gestionada, agrega x-auth-org: <clientOrgUuid>, exactamente igual que con una clave de API de partner. Es solo un encabezado, y un valor vacío cuenta como ausente. Un token de partner que llama a un endpoint a nivel de cliente sin x-auth-org actúa en la organización partner, y la respuesta incluye los encabezados Deprecation y Sunset: consulta Llamadas a la API Partner.

El callback no indica si el usuario es partner. Si llamas a POST /api/integrations/org/submitApiTokenApplication con el token de un usuario partner, la respuesta es 403 Forbidden. Vuelve a intentarlo con el endpoint de partner que se muestra abajo. La CLI de Rhombus detecta las cuentas partner de la misma forma al iniciar sesión, y rhombus login --partner omite esa comprobación.

Emite una clave de API de partner

Llama a POST /api/partner/submitApiTokenApplication con el access token, sin x-auth-org. El cuerpo es el mismo que el del endpoint de organización. El token necesita los tres scopes, y el rol de partner del usuario debe incluir la administración de la API.

curl -X POST "https://api2.rhombussystems.com/api/partner/submitApiTokenApplication" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Acme MSP integration", "permissionGroupUuid": "PARTNER_ROLE_UUID", "authType": "API_TOKEN"}'

La respuesta contiene apiKey. Úsala con x-auth-scheme: api-token y x-auth-apikey. Para actuar dentro de una organización cliente gestionada, agrega x-auth-org: <clientOrgUuid>. Consulta Llamadas a la API Partner, que también explica cómo rotar y renovar claves de partner.

Implementación de referencia

El Rhombus CLI es una referencia de producción para todo lo de esta guía. rhombus login inicia sesión con OAuth y mantiene vigentes los tokens del perfil en lugar de crear una clave de API. cmd/login.go recorre todo el flujo de extremo a extremo: registro dinámico como cliente público, generación de PKCE, servidor de callback local, construcción de la URL de autorización, intercambio de tokens y almacenamiento de los tokens; la CLI los refresca antes de que expiren.

Si algo en tu implementación no funciona, compara tu comportamiento contra el CLI: es el ejemplo canónico.

Solución de problemas

Próximos pasos