code de uso único, que é trocado por um OAuth access token.
O OAuth access token é usado para acessar interfaces de recursos da conta; para chamar a API de modelos, use a API Key correspondente. A autorização OAuth não cria automaticamente uma API Key, ativa serviços ou adiciona saldo.
Escolher o método de integração
O redirecionamento padrão não requer
embed=studio, embed_origin ou postMessage. O modo de componente Studio cria a página de autorização pelo host e mantém a ponte de mensagens; terceiros devem integrar conforme o protocolo de componentes no final deste documento, sem montar esses dois parâmetros por conta própria.
Endpoints e documento de descoberta
A interface de gerenciamento de aplicativos requer autenticação de login na conta e não é uma interface de registro dinâmico anônimo (DCR). Os endereços de descoberta/registro do próprio serviço MCP são entradas diferentes dos endpoints OAuth de conta desta tabela; ao conectar a um MCP específico, opere conforme a documentação e os resultados de descoberta desse serviço.
O documento de descoberta é usado para obter endpoints e capacidades de protocolo. O fluxo atual retorna um OAuth token, não retorna
id_token; não processe como um fluxo completo de login OpenID Connect apenas porque existe o scope openid.
Escopos de permissão: use os nomes de scope atuais
scope é um nome de permissão separado por espaços e sensível a maiúsculas e minúsculas. Novos aplicativos usam permissões específicas como profile:read, email:read, phone:read.
Onde obter as permissões que podem ser solicitadas
Após fazer login, a interface de lista de aplicativos OAuthGET /api/v1/oauth2/applications/ retorna available_scopes; o seletor de permissões da página de gerenciamento de aplicativos usa o mesmo catálogo. Esses são os escopos opcionais que aplicativos comuns de autoatendimento devem usar.
O scopes_supported do Discovery inclui todos os nomes de permissões reconhecidos pela plataforma, não significa que seu aplicativo pode solicitar cada um deles. A autorização real verifica simultaneamente:
- Se a permissão pode ser delegada para esse tipo de aplicativo;
- Se a permissão foi registrada nos escopos permitidos deste aplicativo OAuth;
- Se o usuário atual possui a permissão solicitada.
invalid_scope. A troca do código de autorização e a atualização também são verificadas novamente, e as permissões não são automaticamente preenchidas ou elevadas.
Permissões opcionais para aplicativos comuns de autoatendimento
A seguir está o catálogo atual (2026-10-09); durante a integração, useavailable_scopes como referência.
Por exemplo, para apenas ler o perfil pessoal, use
profile:read; para precisar de e-mail, adicione email:read; para ler API Keys existentes, use profile:read credentials:read. Solicite credentials:write apenas quando realmente precisar criar ou modificar Keys, e adicione offline_access quando precisar atualizar.
Algumas permissões são usadas apenas por aplicativos confiáveis aprovados pela plataforma, como sites:read, sites:write, platform-tokens:read; outras permissões não são abertas para aplicativos OAuth comuns de terceiros. Os tipos de cliente public/confidential descrevem se é possível manter um secret, e não estão relacionados a se o aplicativo é confiável. Aplicativos criados por autoatendimento não podem ativar permissões confiáveis por conta própria.
account é o seletor de permissões de conta usado pelo MCP oficial de gerenciamento de contas especificado, não é um scope de “todas as permissões” para aplicativos de terceiros e não pode ser misturado com outros scopes. Terceiros devem listar claramente as permissões específicas necessárias.
Migrar da documentação antiga
Nomes antigos não são aceitos como aliases compatíveis. Atualize simultaneamente os scopes registrados no aplicativo OAuth, a URL de autorização e sua própria verificação de permissões; modificar a configuração do aplicativo não adiciona permissões a tokens já emitidos, sendo necessário que o usuário autorize novamente.
Etapa 1: registrar o aplicativo OAuth
Abra o Gerenciamento de aplicativos OAuth, crie um aplicativo e preencha:- Nome, descrição, Logo da aplicação: exibidos em um lado da aplicação na página de autorização.
- Tipo de cliente: para clientes puramente frontend, móveis ou desktop, escolha Public; para serviços que podem manter o secret no backend, escolha Confidential.
- Endereço de callback: use HTTPS no ambiente de produção e registre a URL completa que a aplicação realmente usa para processar o callback.
- Permissões: selecione os scopes realmente necessários a partir do catálogo fornecido pela página.
client_id. Clientes Confidential devem armazenar o client_secret no lado do servidor e não podem colocá-lo no HTML, em variáveis de build do frontend ou em URLs. Clientes Public não usam secret para trocar token; mesmo que a resposta de registro inclua esse campo, ele não pode ser tratado como uma credencial que o cliente consegue manter em segredo.
O redirect_uri deve ser exatamente idêntico no registro, na autorização e na troca de token, incluindo o caminho, a barra final e os parâmetros de consulta. Cada conta pode criar no máximo 20 aplicações. O Secret é exibido apenas na criação/rotação; após a rotação, o secret antigo não pode mais realizar trocas que exigem autenticação do cliente.
Etapa 2: o botão inicia a autorização
A cada clique em conectar, gere novos valores aleatórios destate e code_verifier, calcule:
state, o verifier e o endereço de callback na sessão da própria aplicação e, em seguida, abra a página de autorização com os parâmetros codificados em URL:
plain, clientes Public não podem usá-lo. Clientes Confidential também são recomendados a usar S256; se PKCE foi usado ao iniciar a autorização, o verifier correspondente deve ser enviado na troca.
Após o usuário consentir, ele retorna para redirect_uri, e os parâmetros de consulta incluem code e o state retornado sem alterações. Em caso de recusa, retorna error=access_denied, uma descrição do erro e state. Antes de processar o callback, primeiro valide se o state corresponde a esta sessão. O código de autorização é válido por 10 minutos e só pode ser trocado uma vez; após uma falha, a conexão deve ser iniciada novamente, não atualize repetidamente a URL de callback antiga.
Etapa 3: trocar por OAuth token
Clientes Public fazem a troca diretamente pelo navegador ou cliente; clientes Confidential fazem a troca no seu próprio backend. O corpo da solicitação suporta codificação de formulário, e as seguintes variáveis representam os dados obtidos pela aplicação nesta autorização:client_secret no lado do servidor. Atualmente, client_secret_post é suportado; não trate a autenticação de cliente HTTP Basic como um método já suportado.
Na resposta de sucesso, leia access_token, token_type, expires_in e o scope efetivamente concedido. Só haverá refresh_token se offline_access tiver sido solicitado e aprovado. Não trate o OAuth access token como a API Key da API de modelos, e não escreva token, verifier ou código de autorização em logs, eventos de análise ou links compartilhados.
Etapa 4: ler informações do usuário e API Key
Primeiro, use o OAuth access token para solicitar UserInfo:id é o identificador do usuário; profile:read ou openid permitem ler informações básicas (como username, nickname, avatar, is_verified, date_joined, registration_method); e-mail requer email:read, e número de telefone e região requerem phone:read. Não presuma que campos não autorizados estarão sempre presentes.
Quando for necessário usar uma API Key existente e credentials:read tiver sido concedido, use o id de UserInfo como condição de filtro:
count e items, e o campo da Key é items[*].token, não data[0].value. user_id=me não é um ID de usuário válido para esta interface. Para dados em múltiplas páginas, continue lendo de acordo com offset/limit; não trate a primeira página como todas as credenciais.
Selecione a credencial aplicável de acordo com a aplicação, o serviço e o estado de validade; não pegue cegamente a primeira. Uma lista vazia não significa falha de autorização; o usuário pode ainda não ter criado uma Key aplicável. O controle de permissões do OAuth access token e o escopo de serviço, a cota e as condições de expiração da própria API Key são restrições diferentes.
Permitir a leitura de API Keys significa que terceiros podem armazená-las e usá-las. Revogar a solicitação OAuth ou limpar o estado de login da aplicação não invalidará as API Keys já copiadas; o usuário precisa revogar ou rotacionar essa Key separadamente no gerenciamento de credenciais.
Exemplo executável de navegador Public / PKCE
Implante a página abaixo no seuREDIRECT_URI registrado e substitua CLIENT_ID e o endereço de callback. O botão inicia a autorização padrão e, após retornar à mesma página, lê o perfil pessoal e a quantidade de Keys existentes. O exemplo não exibe nem persiste Keys; aplicações de produção consomem os resultados de acordo com o uso real. Primeiro, valide em uma página independente do navegador e, em seguida, faça a validação de acordo com os requisitos de iframe posteriores.
sessionStorage salvo anteriormente possa ser lido. Aplicações de produção devem gerenciar tokens em seu próprio esquema de sessão, lidar com expiração e limpar os parâmetros da URL de autorização após receber a resposta; a interface principal da página deve ser renderizada primeiro, e falhas de rede devem afetar apenas o status da conexão.
iframe em sites white-label
O site do cliente redireciona por conta própria para a página de autorização
Basta usar parâmetros OAuth padrão e seu próprio tratamento de retorno de chamada;window.location.assign() navega o iframe atual, e a página pai permanece no domínio white-label. Não é necessário adicionar embed=studio para o ícone nem implementar o protocolo de mensagens do Studio.
As seguintes condições precisam ser atendidas:
- A página da aplicação e a página de retorno de chamada usam HTTPS, são realmente acessíveis e permitem a incorporação pelo domínio pai white-label via iframe; verifique o
Content-Security-Policy: frame-ancestorse oX-Frame-Optionsde ambas as partes. - O sandbox permite os scripts, formulários e capacidades de origem/armazenamento de que a página precisa. Para oferecer suporte a login por janela pop-up, também são necessárias as capacidades de pop-up correspondentes; priorize o uso da configuração do componente Website fornecida pelo Studio.
- O navegador permite que o cenário de incorporação atual use o armazenamento necessário para o estado de autorização. O estado de login do site white-label e o estado de login do AuthFrontend podem ser diferentes; não se deve presumir que estar conectado ao site white-label significa já estar conectado à página de autorização.
- O serviço de troca de token no retorno de chamada está disponível, e as solicitações entre origens permitem a origem da aplicação; erros de DNS, CORS e HTTP devem exibir um status que permita nova tentativa, e não podem interromper a renderização da página inteira.
Usar a autorização da conta atual do Studio
No Studio, ative OAuth em 「Configurações → Página inicial → Componentes do site」 e preenchaclient_id e o endereço de retorno de chamada registrado. O site e o retorno de chamada devem usar a mesma origem HTTPS e ser diferentes da origem do Studio. A página de terceiros precisa:
- Enviar
acedatacloud:oauth:readyà origin exata do site pai, receber e validaracedatacloud:oauth:init. - O botão gera state e o verificador PKCE, e envia
acedatacloud:oauth:authorize(state, desafio S256); o verificador permanece dentro de sua própria página. - Validar a janela pai, a origin e o state, processar o code ou error em
acedatacloud:oauth:resulte trocar pelo endpoint de token padrão. O Studio exibe a página de autorização na área do componente e, após o usuário consentir, retorna o código de autorização por mensagem; o aplicativo não precisa redirecionar. Quando não há login, retornalogin_required; quando recusado, retornaaccess_denied; quando o tempo de espera expira, retornaauthorization_timeout. A alteração de conta recria o iframe do aplicativo e cancela autorizações não concluídas.
profile:read credentials:read, sem incluir offline_access. Não assuma que um refresh token será sempre recebido. embed=studio e embed_origin são mantidos pelo host do Studio e pela página de autorização; a página do cliente só precisa seguir o protocolo de mensagens.
O exemplo completo do botão está em Guia de integração OAuth do componente de site do Studio.
Ciclo de vida, renovação e revogação
O período de validade padrão do access token é de 15 dias; a renovação ou nova autorização deve ser agendada com base noexpires_in de cada resposta. O refresh token tem validade padrão de 30 dias, e o período é afetado pela configuração do serviço. Não codifique esses dois valores como compromissos permanentes.
Após obter offline_access, é possível chamar:
Erros comuns e aceitação
Antes da entrega, valide pelo menos: callback correto, recusa, state incorreto, code expirado/já consumido, ausência de Key, falha de rede, expiração de token, ausência do scope necessário, bem como o primeiro login e a troca de conta no cenário de iframe. Não salve code, token ou API Key completos nas evidências de teste.
Verificação em duas etapas e nova autorização
Depois que o usuário ativa a verificação em duas etapas, a Ace Data Cloud concluirá na página de autorização a validação do código do autenticador ou do código único de recuperação e, em seguida, entregará o código de autorização. Seu aplicativo continua usando o fluxo OAuth padrão e não deve solicitar, salvar ou encaminhar chaves do autenticador nem códigos de recuperação do usuário. Depois que o usuário ativa, altera, desativa a verificação em duas etapas ou recupera a conta, as sessões de conta anteriores, os tokens de renovação e os tokens de autorização de plataforma relacionados podem se tornar inválidos. Ao receber uma sessão inválida ouinvalid_grant, inicie novamente um fluxo de autorização visível ao usuário; não reutilize repetidamente códigos de autorização antigos nem tente contornar a verificação. O método de autenticação das API Keys comuns do modelo permanece inalterado; se houver suspeita de roubo de conta, verifique e revogue separadamente as API Keys afetadas.
