Subcontas delegadas sem expor chaves: padrão seguro para agências

O problema: autonomia do cliente sem perder controle

Uma agência que gerencia entregáveis para vários clientes costuma precisar de duas coisas que parecem opostas: que cada cliente possa consultar, revisar, enviar ou baixar arquivos com certa autonomia, e que as operações privilegiadas continuem sob o controle técnico da agência. O risco aparece quando se tenta resolver rapidamente compartilhando credenciais, criando um usuário genérico para todos ou deixando que o navegador invoque ações internas com uma chave de API. Esse caminho pode misturar espaços, quebrar a rastreabilidade e tornar muito difícil revogar acessos sem afetar outros clientes.

O objetivo correto não é esconder uma interface, mas separar responsabilidades. O cliente deve ver apenas o seu contexto autorizado; o backend da agência deve executar as ações com privilégios; e o Apification Cloud deve aplicar permissões, visibilidade, grupos, restrições e sessões incorporadas limitadas. Esse padrão permite delegar subcontas sem expor chaves de API, mantendo os segredos no servidor e reduzindo a dependência de operações manuais como mover arquivos, gerar links ou verificar trabalhos de transformação um por um.

• Evite entregar credenciais de API ao cliente ou incluí-las em JavaScript.
• Não use uma conta compartilhada para vários clientes se você precisa de isolamento operacional.
• Defina desde o início quais ações são de usuário e quais são de backend.
• Trate cada exposição de conteúdo como uma exceção explícita sobre recursos privados por padrão.

Modelo mental: três camadas separadas

A primeira camada é a interface incorporada. O Apification permite integrar o Cloud por meio de iframe, configuração herdada e temas visuais, de modo que uma agência ou reseller possa oferecer uma experiência integrada no seu próprio ecossistema. Nesse modelo, a sessão do iframe deve ser construída antes de ser exibida: identidade, política efetiva e configuração visual são resolvidas no servidor a cada inicialização. A sessão incorporada pode ser limitada à subconta, ao usuário e aos recursos permitidos, o que impede que o navegador decida por conta própria o que pode abrir.

A segunda camada é o backend próprio. É ali que vivem as credenciais de API, os segredos de webhook e o material de assinatura, porque o Apification especifica que eles devem permanecer no servidor e que o navegador deve receber apenas contexto limitado ou temporário. A terceira camada são os controles do Cloud: permissões, usuários, grupos, visibilidade, restrições, OTP, autenticação externa quando aplicável e janelas de publicação. A regra de design é simples: a interface orienta o usuário, o backend executa ações privilegiadas e o Cloud conserva a política de acesso associada ao recurso.

• Iframe: experiência de usuário e seleção dentro de um contexto limitado.
• Backend: criação de sessões assinadas, chamadas de API e validação de regras do cliente.
• Cloud: arquivos, pastas, serviços editáveis, resultados, histórico, permissões e visibilidade.
• Webhooks: notificações de eventos com assinatura, novas tentativas, histórico e estatísticas.

O que o Apification oferece a esse padrão

O Apification reúne as peças necessárias para uma delegação controlada. O Cloud conserva arquivos, pastas, serviços editáveis e resultados gerados dentro de um mesmo espaço de trabalho organizado e versionado. Os novos recursos são privados por padrão e só são publicados ou compartilhados quando sua visibilidade ou seus destinatários são configurados expressamente. Além disso, eles podem ser compartilhados com usuários ou grupos sem alterar a visibilidade pública, algo importante quando uma agência precisa dar acesso interno a revisores do cliente sem transformar um entregável em público.

Para a integração, o Apification oferece API REST servidor a servidor para gerenciar recursos Cloud, usuários, configuração e trabalhos de transformação a partir do backend, além de um contrato OpenAPI baixável com esquemas de requisição e resposta. Ele também permite integrar Cloud e serviços por meio de iframe, API, webhooks e JavaScript, mas o ponto central é não confundir “integração com JavaScript” com “segredos no navegador”. Para operações assíncronas, os webhooks assinados com novas tentativas, histórico e estatísticas são preferíveis ao polling em produção quando se esperam eventos de transformação concluída ou com falha.

• Use chaves de API específicas e com apenas os scopes necessários.
• Apoie-se no OpenAPI para validar contratos antes de programar.
• Utilize webhooks em produção para reduzir consultas repetitivas e melhorar a rastreabilidade.
• Reserve OTP para interações públicas; use usuários, grupos e visibilidade para acesso interno.

Arquitetura recomendada para subcontas delegadas

O fluxo recomendado começa no portal da agência. O usuário do cliente se autentica no sistema da agência e solicita abrir sua área de arquivos ou uma operação específica. O backend valida a que cliente ele pertence, qual função possui e quais recursos pode usar. Só então solicita uma sessão iframe assinada e de curta duração a partir do backend confiável, com o contexto do cliente isolado: subconta, usuário e recursos permitidos. O navegador recebe essa sessão limitada, não uma chave de API nem um segredo reutilizável.

Quando o cliente precisa de uma ação privilegiada, como criar um trabalho de transformação, consultar um recurso ou preparar um download transformado, o navegador deve chamar o backend da agência, não diretamente com credenciais permanentes. O backend aplica regras de negócio, invoca a API REST do Apification com autenticação Bearer a partir do servidor e registra a ação. Se o host e o iframe se coordenarem por meio de mensagens do navegador, essas mensagens devem ser validadas: o receptor deve verificar origem, intenção e dados esperados, seguindo o princípio geral de validação de comunicações entre janelas.

• Passo 1: autentique o cliente no portal da agência.
• Passo 2: resolva no servidor identidade, política efetiva e tema visual.
• Passo 3: solicite uma sessão iframe assinada, limitada e de curta duração.
• Passo 4: execute chamadas REST apenas a partir do backend com chave de scopes mínimos.
• Passo 5: registre eventos e respostas para auditoria operacional.

Delegação por cliente: permissões, espaços e regras

A separação não deve depender apenas do nome de uma pasta. No Apification, mover um item Cloud modifica sua organização, não sua identidade: suas propriedades e regras de acesso continuam associadas ao mesmo item. Isso é útil para reorganizar entregáveis sem perder controles, mas também demonstra por que o isolamento deve se basear em permissões, usuários, grupos, visibilidade e recursos autorizados, não em convenções frágeis como “tudo o que estiver em /cliente-a”. A agência deve documentar a matriz de acesso por cliente e revisá-la quando o contrato de serviço mudar.

Uma matriz prática distingue pelo menos cinco ações: enviar ou incorporar arquivos, transformar ou processar conteúdo, revisar versões, baixar originais ou formatos gerados, e publicar links ou acessos. O Cloud permite baixar o arquivo fonte ou gerar um formato compatível a partir do fluxo de compartilhamento, por isso convém decidir quem pode entregar originais e quem deve receber apenas derivados. Se forem usados serviços editáveis, como documentos de escritório, edição de imagens ou editores multimídia, a mesma lógica se aplica: o cliente não precisa de permissão universal, mas sim do conjunto mínimo de ações para seu caso.

• Defina grupos por cliente ou por função dentro do cliente.
• Separe revisão, transformação, download e publicação como permissões distintas no seu design.
• Evite que uma mudança de pasta seja o único mecanismo de controle.
• Mantenha um procedimento de revogação quando um contato do cliente deixar de participar.

Operações típicas e como automatizá-las

Em uma operação diária, o cliente pode selecionar arquivos a partir do iframe, revisar entregáveis no Cloud, baixar um original ou pedir uma versão transformada. A agência, por sua vez, pode criar trabalhos a partir do backend, aplicar regras do cliente e usar o histórico dos itens para revisar versões anteriores ou restaurar conteúdo quando necessário. Essa abordagem reduz e-mails soltos e evita que a equipe interna precise atuar como intermediária para cada download ou revisão básica.

Para processos assíncronos, desenhe em torno de eventos. Se uma transformação for concluída ou falhar, um webhook assinado pode avisar o backend da agência. Esse backend deve verificar a assinatura com o segredo armazenado no servidor, deduplicar eventos e atualizar seu próprio estado. O Apification suporta escritas idempotentes por meio de uma chave de idempotência em operações compatíveis, portanto as ações que poderiam se repetir por novas tentativas, duplo clique ou reconexões devem enviar uma chave estável. Assim você evita criar trabalhos duplicados ou publicar duas vezes o mesmo resultado.

• Use webhooks para encerramento de trabalhos e erros, não apenas consultas periódicas.
• Verifique a assinatura antes de confiar no conteúdo do evento.
• Armazene identificadores de eventos ou resultados para deduplicar.
• Aplique chaves de idempotência em escritas compatíveis que possam se repetir.
• Mantenha um registro operacional de quem solicitou, qual recurso foi afetado e qual foi o resultado.

Erros frequentes e modos de falha

O erro mais grave é colocar chaves em JavaScript. Mesmo que uma interface seja privada ou esteja atrás de login, qualquer segredo entregue ao navegador deve ser considerado exposto. Outra falha comum é usar um único usuário para todos os clientes: pode parecer cômodo no início, mas impede atribuir ações, dificulta revogar acessos e aumenta o impacto de qualquer erro de configuração. Também é perigoso confiar apenas em nomes de pasta, porque a organização visual não substitui regras de acesso associadas a recursos e usuários.

Na automação, as falhas costumam aparecer por não verificar assinaturas de webhook, processar o mesmo evento duas vezes ou assumir que uma importação pontual equivale a sincronização contínua. Se uma entrega de webhook for tentada novamente e seu backend não for idempotente, você pode duplicar trabalhos ou notificações. Se não testar com usuários de menor privilégio, pode descobrir tarde que uma função consegue baixar originais quando deveria apenas ver transformados. A defesa é testar os casos negativos: usuário errado, recurso de outro cliente, sessão expirada, assinatura inválida e repetição de evento.

• Não exponha Bearer tokens, segredos de webhook nem material de assinatura no frontend.
• Não misture clientes sob uma única identidade operacional.
• Não processe webhooks sem verificar assinatura e deduplicar.
• Não trate uma importação pontual de provedores externos como sincronização contínua.
• Não conceda scopes de API amplos se a integração precisa apenas de uma parte.

Checklist de implementação antes da produção

Antes de abrir o acesso a clientes, prepare uma checklist técnica e outra operacional. Na técnica, crie uma chave de API específica para a integração e conceda somente os scopes necessários de conta, Cloud, transformações, usuários ou webhooks. Guarde a chave e os segredos em variáveis ou armazenamento de servidor, nunca no cliente. Implemente validação de cliente em cada endpoint interno: nenhuma requisição do navegador deve poder indicar livremente outro cliente, subconta ou recurso sem que o backend verifique isso contra sua própria autorização.

Na checklist operacional, documente quem pode enviar, transformar, revisar, baixar, compartilhar e revogar. Crie testes com usuários de menor privilégio, valide sessões iframe expiradas e revise se os recursos continuam privados salvo publicação expressa. Para webhooks, teste assinatura inválida, evento duplicado e nova tentativa. Para escritas, aplique idempotência quando disponível. Por fim, defina como retirar acesso de um cliente ou usuário sem afetar outros: essa capacidade de revogação é uma das principais razões para separar subcontas e não depender de credenciais compartilhadas.

• Matriz de permissões por cliente, função e ação.
• Chaves de API específicas, scopes mínimos e segredos apenas no servidor.
• Sessão iframe assinada, curta e criada a partir de backend confiável.
• Validação de subconta, usuário e recurso em cada operação.
• Verificação de assinaturas de webhook, deduplicação e idempotência.
• Testes negativos com funções limitadas e recursos de outros clientes.
• Plano documentado de revogação de usuários, grupos e acessos publicados.

Perguntas frequentes