Saltar para o conteúdo principal
Permita que os usuários autorizem seu aplicativo a acessar seu perfil do Ace Data Cloud, assinaturas de serviços, API Key, uso ou pedidos. Use o padrão Authorization Code + S256 PKCE: o aplicativo abre a página de autorização, o usuário consente e então recebe um 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 OAuth GET /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:
  1. Se a permissão pode ser delegada para esse tipo de aplicativo;
  2. Se a permissão foi registrada nos escopos permitidos deste aplicativo OAuth;
  3. Se o usuário atual possui a permissão solicitada.
Permissões desconhecidas, não registradas, não permitidas para delegação ou não possuídas pelo usuário retornam 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, use available_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.
Salve o 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 de state e code_verifier, calcule:
Armazene o 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:
Clientes Public devem enviar PKCE S256. Embora o Discovery também liste 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:
Clientes Confidential também precisam adicionar o campo de formulário 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:
Os campos retornados dependem do scope: 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:
A lista retornada usa 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 seu REDIRECT_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.
O retorno de chamada e a entrada do exemplo devem estar na mesma origem e na mesma aba do navegador/iframe para que o 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-ancestors e o X-Frame-Options de 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.
O lado esquerdo da página de autorização lê o Logo da aplicação OAuth; o lado direito lê o favicon/logo desse Site quando o navegador pode fornecer a origem pai e o domínio pai passa pela validação de site verificado, caso contrário exibe o ícone padrão. Isso apenas determina a exibição da marca, não estabelece uma sessão de login nem fornece permissões da conta à página do cliente. Limitação atual: quando o OAuth comum precisa de um novo login dentro de um iframe, ainda há uma lacuna no fluxo para retornar à página de autorização após a conclusão do login. Antes do lançamento, é obrigatório validar separadamente “Auth conectado” e “Auth não conectado/expirado”. Antes que essa lacuna seja corrigida e validada, o primeiro login pode usar uma página independente para concluir o OAuth padrão ou usar a autorização do componente Studio abaixo; não prometa que todos os cenários de iframe são utilizáveis apenas com base nos resultados de testes conectados.

Usar a autorização da conta atual do Studio

No Studio, ative OAuth em 「Configurações → Página inicial → Componentes do site」 e preencha client_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:
  1. Enviar acedatacloud:oauth:ready à origin exata do site pai, receber e validar acedatacloud:oauth:init.
  2. 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.
  3. Validar a janela pai, a origin e o state, processar o code ou error em acedatacloud:oauth:result e 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, retorna login_required; quando recusado, retorna access_denied; quando o tempo de espera expira, retorna authorization_timeout. A alteração de conta recria o iframe do aplicativo e cancela autorizações não concluídas.
O componente solicita atualmente 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 no expires_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:
A renovação retorna novos tokens, e o aplicativo deve salvar os valores mais recentes. Durante a renovação, será verificado se o aplicativo ainda é válido, se o usuário está disponível e se as permissões ainda foram concedidas. Em caso de falha, limpe o próprio estado de conexão e autorize novamente. A implementação atual de renovação OAuth não garante que o refresh token antigo se torne inválido imediatamente após a renovação. Não considere a obtenção de um novo token como confirmação de que o token antigo foi revogado, nem use a rotação de secret como substituta para encerrar tokens existentes. A chamada para a solicitação de revogação é:
O endpoint de revogação atual retorna HTTP 200, mas não implementa a invalidação imediata de JWTs já emitidos. O aplicativo deve limpar os tokens que ele próprio armazenou e não pode considerar o 200 como prova de que todos os tokens emitidos ou API Keys se tornaram inválidos. Para API Keys vazadas ou copiadas, revogue ou rotacione separadamente as credenciais correspondentes.

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