Saltar al contenido principal
Permite que los usuarios autoricen a tu aplicación a acceder a su perfil de Ace Data Cloud, suscripciones de servicios, API Key, uso u órdenes. Usa el estándar Authorization Code + S256 PKCE: la aplicación abre la página de autorización, el usuario recibe un code de un solo uso después de aceptar, y luego lo intercambia por un OAuth access token. El OAuth access token se utiliza para acceder a las interfaces de recursos de la cuenta; para llamar a la API de modelos se utiliza la API Key correspondiente. La autorización OAuth no crea automáticamente una API Key, activa servicios ni aumenta el saldo.

Elegir el método de integración

La redirección estándar no requiere embed=studio, embed_origin ni postMessage. El modo de componente de Studio crea la página de autorización y mantiene el puente de mensajes por parte del host; terceros deben integrarse según el protocolo de componentes al final de este documento, y no deben concatenar estos dos parámetros por su cuenta.

Endpoints y documento de descubrimiento

La interfaz de administración de aplicaciones requiere autenticación de inicio de sesión de la cuenta y no es una interfaz de registro dinámico anónimo (DCR). Las direcciones de descubrimiento/registro propias del servicio MCP son puntos de entrada distintos de los endpoints OAuth de cuenta de esta tabla; al conectar un MCP específico, opera según la documentación y los resultados de descubrimiento de ese servicio. El documento de descubrimiento se utiliza para obtener endpoints y capacidades del protocolo. El flujo actual devuelve OAuth token y no devuelve id_token; no lo proceses como un flujo completo de inicio de sesión de OpenID Connect solo porque exista el scope openid.

Alcances de permisos: usa los nombres de scope actuales

scope es un nombre de permiso separado por espacios y distingue entre mayúsculas y minúsculas. Las nuevas aplicaciones usan permisos específicos como profile:read, email:read, phone:read, etc.

Dónde obtener los permisos que se pueden solicitar

Después de iniciar sesión, la interfaz de lista de aplicaciones OAuth GET /api/v1/oauth2/applications/ devuelve available_scopes; el selector de permisos de la página de administración de aplicaciones usa el mismo catálogo. Estos son los alcances opcionales que deben utilizar las aplicaciones normales de autoservicio. Los scopes_supported de Discovery incluyen todos los nombres de permisos reconocidos por la plataforma, pero no representan que tu aplicación pueda solicitar cada uno de ellos. La autorización real verifica simultáneamente:
  1. si el permiso puede delegarse a este tipo de aplicación;
  2. si el permiso ya está registrado en los alcances permitidos de esta aplicación OAuth;
  3. si el usuario actual posee el permiso solicitado.
Los permisos desconocidos, no registrados, no permitidos para delegación o que el usuario no posee devolverán invalid_scope. También se vuelven a verificar al intercambiar y renovar el código de autorización; los permisos no se completarán ni elevarán automáticamente.

Permisos opcionales para aplicaciones normales de autoservicio

El siguiente es el catálogo actual (2026-10-09); al realizar la integración, prevalece available_scopes. Por ejemplo, para leer únicamente el perfil personal usa profile:read; si también necesitas el correo electrónico, añade email:read; para leer API Key existentes usa profile:read credentials:read. Solicita credentials:write solo cuando realmente necesites crear o modificar Key, y añade offline_access cuando necesites renovar. Algunos permisos solo están disponibles para aplicaciones de confianza aprobadas por la plataforma, por ejemplo sites:read, sites:write, platform-tokens:read; otros permisos no están abiertos a aplicaciones OAuth normales de terceros. Los tipos de cliente public/confidential describen si se puede conservar el secret y no están relacionados con si la aplicación es de confianza. Las aplicaciones creadas por autoservicio no pueden habilitar permisos de confianza por sí mismas. account es un selector de permisos de cuenta utilizado por el MCP oficial especificado de administración de cuentas, no es un scope de “todos los permisos” para aplicaciones de terceros y no puede combinarse con otros scopes. Los terceros deben enumerar explícitamente los permisos específicos que necesitan.

Migrar desde documentación antigua

Los nombres antiguos no se aceptan como alias compatibles. Actualiza también los scopes registrados de la aplicación OAuth, la URL de autorización y tus propias verificaciones de permisos; modificar la configuración de la aplicación no añade permisos a los token ya emitidos, por lo que el usuario debe autorizar de nuevo.

Paso 1: Registrar una aplicación OAuth

Abre la Administración de aplicaciones OAuth, crea una aplicación y completa:
  • Nombre, descripción, Logo de la aplicación: se muestran en un lado de la aplicación en la página de autorización.
  • Tipo de cliente: para frontend puro, clientes móviles o de escritorio, seleccione Public; para servicios que pueden guardar el secret en el backend, seleccione Confidential.
  • Dirección de callback: use HTTPS en el entorno de producción y registre la URL completa que la aplicación realmente utiliza para procesar el callback.
  • Permisos: seleccione los scopes realmente necesarios del catálogo proporcionado por la página.
Guarde el client_id. Los clientes Confidential deben guardar el client_secret en el servidor; no puede colocarse en HTML, variables de compilación del frontend ni URL. Los clientes Public no usan secret para intercambiar tokens; incluso si la respuesta de registro incluye este campo, no debe tratarlo como una credencial que el cliente pueda mantener secreta. El redirect_uri debe ser exactamente igual durante el registro, la autorización y el intercambio de tokens, incluida la ruta, la barra final y los parámetros de consulta. Cada cuenta puede crear como máximo 20 aplicaciones. El Secret solo se muestra al crearlo/rotarlo; después de la rotación, el secret anterior ya no puede continuar realizando intercambios que requieran autenticación del cliente.

Paso 2: el botón inicia la autorización

En cada clic de conexión, genere nuevos state y code_verifier aleatorios, calcule:
Guarde state, verifier y la dirección de callback en la propia sesión de la aplicación, y luego abra la página de autorización con los parámetros codificados en URL:
Los clientes Public deben enviar PKCE S256. Aunque Discovery todavía enumera plain, los clientes Public no pueden usarlo. También se recomienda que los clientes Confidential usen S256; si se utilizó PKCE al iniciar la autorización, se debe enviar el verifier correspondiente al intercambiarlo. Después de que el usuario acepte, vuelve a redirect_uri, y los parámetros de consulta contienen code y el state devuelto sin cambios. Al rechazar, se devuelven error=access_denied, la descripción del error y state. Antes de procesar el callback, primero verifique que state coincida con esta sesión. El código de autorización tiene una validez de 10 minutos y solo puede intercambiarse una vez; después de un fallo, debe iniciar la conexión de nuevo y no actualizar repetidamente la URL del callback anterior.

Paso 3: intercambiar el token OAuth

Los clientes Public intercambian directamente desde el navegador o cliente; los clientes Confidential intercambian en su propio backend. El cuerpo de la solicitud admite codificación de formulario; las siguientes variables representan los datos obtenidos por la aplicación en esta autorización:
Los clientes Confidential también deben añadir el campo de formulario client_secret en el servidor. Actualmente se admite client_secret_post; no considere la autenticación de cliente HTTP Basic como un método ya compatible. En la respuesta exitosa, lea access_token, token_type, expires_in y el scope realmente concedido. Solo hay refresh_token si se solicita y aprueba offline_access. No trate el OAuth access token como la API Key de la API del modelo, y no escriba token, verifier ni código de autorización en registros, eventos de análisis o enlaces compartidos.

Paso 4: leer la información del usuario y la API Key

Primero use el OAuth access token para solicitar UserInfo:
Los campos devueltos dependen del scope: id es el identificador de usuario; con profile:read u openid se pueden leer datos básicos (como username, nickname, avatar, is_verified, date_joined, registration_method); el correo electrónico requiere email:read, y el teléfono y la región requieren phone:read. No dependa de que los campos no autorizados estén siempre presentes. Cuando se necesite una API Key existente y se haya concedido credentials:read, use el id de UserInfo como condición de filtrado:
La lista devuelta usa count e items, y el campo Key es items[*].token, no data[0].value. user_id=me no es un ID de usuario válido para esta interfaz. Para datos de varias páginas, continúe leyendo según offset/limit; no trate la primera página como todas las credenciales. Seleccione las credenciales aplicables según la aplicación, el servicio y el estado de validez; no tome ciegamente la primera. Una lista vacía no significa que la autorización haya fallado; puede que el usuario aún no haya creado una Key aplicable. El control de permisos del OAuth access token y el ámbito de servicio, cuota y condiciones de expiración de la propia API Key son restricciones diferentes. Permitir la lectura de la API Key significa que un tercero puede guardarla y utilizarla. Revocar la solicitud OAuth o borrar el estado de inicio de sesión de la aplicación no invalidará la API Key ya copiada; el usuario debe revocar o rotar esa Key por separado en la gestión de credenciales.

Ejemplo ejecutable de navegador Public / PKCE

Despliegue la siguiente página en el REDIRECT_URI que registró, sustituya CLIENT_ID y la dirección de callback. El botón inicia la autorización estándar y, después de volver a la misma página, lee el perfil y la cantidad de Keys existentes. El ejemplo no muestra ni persiste Keys; las aplicaciones de producción consumen los resultados según el uso real. Primero valide en una página de navegador independiente y luego realice la aceptación según los requisitos de iframe posteriores.
La devolución de llamada y el punto de entrada del ejemplo deben estar en el mismo origen y en la misma pestaña del navegador/iframe para poder leer el sessionStorage guardado anteriormente. Las aplicaciones de producción deben gestionar los tokens en su propio esquema de sesión, manejar la expiración y eliminar los parámetros de URL de autorización después de recibir la respuesta; la interfaz principal de la página debe renderizarse primero, y los fallos de red solo deben afectar al estado de conexión.

iframe en sitios de marca blanca

El sitio del cliente redirige por sí mismo a la página de autorización

Basta con usar los parámetros estándar de OAuth y su propio manejo de devolución de llamada; window.location.assign() navega el iframe actual, y la página principal permanece en el dominio de marca blanca. No es necesario añadir embed=studio para el icono ni implementar el protocolo de mensajes de Studio. Se deben cumplir las siguientes condiciones:
  • La página de la aplicación y la página de devolución de llamada usan HTTPS, son realmente accesibles y permiten la incrustación mediante iframe desde el dominio padre de marca blanca; comprueba Content-Security-Policy: frame-ancestors y X-Frame-Options de ambas partes.
  • El sandbox permite los scripts, formularios y capacidades de origen/almacenamiento que necesita la página. Si se admite el inicio de sesión mediante ventana emergente, también se necesitan las capacidades correspondientes para ventanas emergentes; se debe priorizar la configuración del componente Website proporcionado por Studio.
  • El navegador permite que el escenario de incrustación actual use el almacenamiento necesario para el estado de autorización. El estado de inicio de sesión del sitio de marca blanca y el estado de inicio de sesión de AuthFrontend pueden ser diferentes; no se debe asumir que iniciar sesión en el sitio de marca blanca significa que ya se inició sesión en la página de autorización.
  • El servicio de intercambio de tokens en la devolución de llamada está disponible, y las solicitudes entre orígenes permiten el origen de la aplicación; los errores de DNS, CORS y HTTP deben mostrar un estado que permita reintentar, y no deben detener el renderizado de toda la página.
La parte izquierda de la página de autorización lee el Logo de la aplicación OAuth; la parte derecha lee el favicon/logo de ese Site cuando el navegador puede proporcionar el origen padre y el dominio padre pasa la verificación de sitio validado; de lo contrario, muestra el icono predeterminado. Esto solo determina la presentación de marca, no establece una sesión de inicio de sesión ni proporciona permisos de cuenta a la página del cliente. Limitación actual: cuando OAuth normal necesita volver a iniciar sesión dentro de un iframe, todavía existe una carencia en el flujo para continuar de vuelta a la página de autorización después de completar el inicio de sesión. Antes del lanzamiento, se debe validar por separado “Auth ya ha iniciado sesión” y “Auth no ha iniciado sesión/ha expirado”. Hasta que esta carencia se corrija y verifique, el primer inicio de sesión puede completar OAuth estándar en una página independiente, o se puede usar la autorización del componente Studio de abajo; no prometas que todos los escenarios de iframe funcionan basándote únicamente en resultados de pruebas con sesión iniciada.

Usar la autorización de la cuenta actual de Studio

Activa OAuth en Studio «Configuración → Inicio → Componentes del sitio web», completa client_id y la dirección de devolución de llamada registrada. El sitio web y la devolución de llamada deben usar el mismo origen HTTPS y ser diferentes del origen de Studio. La página de terceros necesita:
  1. Enviar acedatacloud:oauth:ready al origin exacto del sitio padre, recibir y validar acedatacloud:oauth:init.
  2. El botón genera state y el verifier de PKCE, envía acedatacloud:oauth:authorize (state, desafío S256); el verifier permanece dentro de su propia página.
  3. Validar la ventana padre, el origin y state, manejar code o error en acedatacloud:oauth:result, e intercambiar según el punto de conexión de token estándar. Studio muestra la página de autorización en el área de componentes y, tras el consentimiento del usuario, devuelve el código de autorización mediante un mensaje; la aplicación no necesita redirigir. Cuando no hay inicio de sesión, devuelve login_required; al rechazar, devuelve access_denied; al agotarse el tiempo de espera, devuelve authorization_timeout. Un cambio de cuenta reconstruirá el iframe de la aplicación y cancelará las autorizaciones no completadas.
El componente solicita actualmente profile:read credentials:read, sin incluir offline_access. No supongas que necesariamente se recibirá un refresh token. embed=studio y embed_origin son mantenidos por el host de Studio y la página de autorización; la página del cliente solo debe cumplir el protocolo de mensajes. El ejemplo completo del botón se encuentra en la Guía de integración OAuth de componentes web de Studio.

Ciclo de vida, renovación y revocación

El período de validez predeterminado del access token es de 15 días; se debe programar la renovación o reautorización según el expires_in de cada respuesta. El refresh token tiene una validez predeterminada de 30 días, y el plazo está sujeto a la configuración del servicio. No codifiques estos dos valores como compromisos permanentes. Tras obtener offline_access, se puede llamar a:
La renovación devolverá nuevos tokens, y la aplicación debe guardar los valores más recientes. Durante la renovación se verificará si la aplicación sigue siendo válida, si el usuario está disponible y si los permisos continúan concedidos. Si falla, elimina tu propio estado de conexión y vuelve a autorizar. La implementación actual de renovación OAuth no garantiza que el refresh token anterior quede invalidado inmediatamente después de la renovación. No consideres la obtención de un nuevo token como prueba de que el token anterior ha sido revocado, ni sustituyas la terminación de tokens existentes por la rotación de secretos. La forma de llamar a la solicitud de revocación es:
El endpoint de revocación actual devuelve HTTP 200, pero no implementa la invalidación inmediata de los JWT ya emitidos. La aplicación debe eliminar los tokens que haya guardado y no puede considerar un 200 como prueba de que todos los tokens emitidos o las API Keys han quedado invalidados. Las API Keys filtradas o copiadas deben revocarse o rotarse por separado.

Errores comunes y validación

Antes de la entrega, verifica al menos: callback correcto, rechazo, state erróneo, code caducado/ya consumido, sin Key, fallo de red, token caducado, falta del scope requerido, así como el primer inicio de sesión y el cambio de cuenta en escenarios de iframe. No guardes el code, token ni API Key completos en las evidencias de prueba.

Verificación en dos pasos y reautorización

Después de que el usuario active la verificación en dos pasos, Ace Data Cloud completará en la página de autorización la validación del código del autenticador o del código de recuperación de un solo uso, y luego entregará el código de autorización. Tu aplicación debe seguir utilizando el flujo OAuth estándar y no debe solicitar, guardar ni reenviar las claves del autenticador ni los códigos de recuperación. Después de que el usuario active, cambie o desactive la verificación en dos pasos, o recupere su cuenta, las sesiones de cuenta anteriores, los tokens de renovación y los tokens de autorización de plataforma relacionados pueden invalidarse. Al recibir una sesión inválida o invalid_grant, vuelve a iniciar un flujo de autorización visible para el usuario; no reutilices repetidamente códigos de autorización antiguos ni intentes eludir la verificación. El método de autenticación de las API Keys normales del modelo permanece sin cambios; si se sospecha que la cuenta ha sido comprometida, se deben comprobar y revocar por separado las API Keys afectadas.