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 OAuthGET /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:
- si el permiso puede delegarse a este tipo de aplicación;
- si el permiso ya está registrado en los alcances permitidos de esta aplicación OAuth;
- si el usuario actual posee el permiso solicitado.
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, prevaleceavailable_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.
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 nuevosstate y code_verifier aleatorios, calcule:
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:
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: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: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:
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 elREDIRECT_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.
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-ancestorsyX-Frame-Optionsde 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.
Usar la autorización de la cuenta actual de Studio
Activa OAuth en Studio «Configuración → Inicio → Componentes del sitio web», completaclient_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:
- Enviar
acedatacloud:oauth:readyal origin exacto del sitio padre, recibir y validaracedatacloud:oauth:init. - 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. - 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, devuelvelogin_required; al rechazar, devuelveaccess_denied; al agotarse el tiempo de espera, devuelveauthorization_timeout. Un cambio de cuenta reconstruirá el iframe de la aplicación y cancelará las autorizaciones no completadas.
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 elexpires_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:
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 oinvalid_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.
