Aplicativos (OAuth)

Cadastrar e gerenciar seu aplicativo de "Entrar com Asender" no painel: credenciais, escopos, revisão e testadores.

Aplicativos (OAuth)

Um aplicativo (app) Asender é a sua integração registrada para agir em nome de usuários de outras contas, com o consentimento deles. Com um app você oferece o botão Entrar com Asender, lê dados pela API pública e conecta agentes de IA pelo servidor MCP, sempre com os escopos que cada usuário aprovou.

Este guia mostra como criar e manter um app no painel, o ciclo de vida até a publicação e como clientes MCP se registram sozinhos. O fluxo OAuth em si (passo a passo, tokens e erros) está em Entrar com Asender.

• Servidor de autorização: https://auth.asender.net
• Painel: https://admin.asender.net
• API de recursos: https://api.asender.net

App ou chave de API?

Se o código só acessa a sua conta, use chave de API: é mais simples. Crie um app quando outras pessoas precisam entrar com a conta Asender delas no seu produto.

Criar um app no painel

1. Entre em https://admin.asender.net, escolha a conta e abra Desenvolvedores > Aplicativos (https://admin.asender.net/t/<conta>/aplicativos).
2. Preencha Novo aplicativo e confirme com Criar aplicativo.

Quem pode: só quem é owner ou admin da conta enxerga e gerencia os apps dela. Quem tem outro papel recebe a mensagem "Só owner e admin da conta gerenciam aplicativos".

Os escopos que a tela oferece são de identidade (profile, email, offline_access) e de leitura (account:read, leads:read, conversions:read, forms:read, analytics:read, campaigns:read, email:read, messaging:read, conversations:read, journeys:read, logs:read). Peça só o que o app usa: a revisão pesa isso (veja O que a revisão confere).

Confidencial ou público

PKCE S256 é obrigatório nos dois tipos. Um app público que envie client_secret recebe invalid_client. Na troca do code, o redirect_uri precisa ser o mesmo do /authorize, inclusive a porta.

O segredo aparece uma vez

Para app confidencial, o client_secret é mostrado uma única vez, logo depois de criar (e depois de girar). A tela o mantém só até você fechá-la; a Asender não consegue mostrá-lo de novo. Guarde-o no cofre ou nas variáveis de ambiente do seu backend, nunca no navegador, em app mobile, repositório ou log.

Girar o segredo (botão Girar segredo no detalhe do app) emite um novo e invalida o atual na hora: o app para de trocar tokens até receber o novo. App público não tem segredo, então não há o que girar.

Limites

Excluir um app o desativa e revoga todas as autorizações e refresh tokens.

Ciclo de vida

Todo app nasce em Desenvolvimento. Enquanto não está publicado, só a equipe dele consegue autorizá-lo; assim você integra e testa sem esperar ninguém.

Quem não pode autorizar vê a tela "Este aplicativo não está disponível" e o app recebe um erro no redirect. O motivo da recusa ou da suspensão aparece no app, no painel.

Testadores

Em Testadores, convide por e-mail pessoas que já têm usuário Asender (sem usuário com aquele e-mail, o convite falha). O testador pode autorizar o app mesmo em desenvolvimento, em revisão ou recusado, sem ser membro da sua conta. São até 25 por app, e você remove quando quiser.

Pedir revisão

Quando o app estiver pronto, Pedir revisão o envia à equipe Asender. Antes disso, preencha o site do app: sem ele o pedido é recusado. Só se pede revisão de app em Desenvolvimento ou Recusado, e há no máximo uma revisão pendente por app. A equipe aprova (o app vira Publicado e Verificado, com os escopos aprovados, que podem ser menos que os pedidos) ou recusa, sempre com um motivo registrado no Histórico de revisões do app. Quem revisa não decide apps de uma conta da qual é membro.

O que a revisão confere

Não há prazo garantido de resposta. A equipe avalia, entre outros pontos:

• Identidade e site reais: o site do app existe, é do responsável pelo app e explica o que ele faz; nome e logo não imitam outro produto nem a própria Asender.
• Redirects no domínio do app: as redirect_uri apontam para domínios que o app controla (loopback é aceito para apps públicos e para desenvolvimento).
• Escopos mínimos e justificados: cada escopo pedido tem um uso claro no app; o que não for necessário sai.
• Política de privacidade: o app informa ao usuário como trata os dados lidos da Asender.

Mudar um app já publicado

• Ampliar escopos abre uma nova revisão. Até a aprovação, o escopo novo vale só para membros da conta e testadores; os demais usuários continuam com os escopos já aprovados.
• Reduzir escopos vale na hora.
• Trocar os redirects de um app publicado não abre revisão; mesmo assim, mantenha-os no seu domínio.

Suspensão

A equipe pode suspender um app a qualquer momento (por exemplo, por abuso ou denúncia). A suspensão revoga as autorizações e os refresh tokens existentes e o app deixa de funcionar para todos até uma reativação. Uma autorização revogada na suspensão não volta sozinha: o usuário autoriza de novo.

Selo Verificado e Não verificado

Na tela de consentimento o usuário vê o nome do app junto do domínio dele, os escopos em português, a conta em que o app vai operar e para onde voltará (Após autorizar, você volta para).

• Verificado pela Asender: o app passou pela revisão (ou é da própria Asender). O logo remoto só aparece nesse caso.
• Não verificado pela Asender: aviso "A Asender não revisou este aplicativo. Só continue se você confia em domínio", com os domínios de destino em destaque. Vale para clientes registrados automaticamente e para qualquer app publicado que perca o selo. Um app não verificado só recebe escopos de identidade e leitura, mesmo que declare mais.
• Aplicativo em desenvolvimento: faixa "disponível só para a equipe dele e testadores", para apps em desenvolvimento, em revisão ou recusados.
• Clientes de IA/MCP registrados automaticamente mostram "Cliente de IA/MCP registrado automaticamente".

Clientes registrados automaticamente (MCP)

Clientes MCP (Claude, ChatGPT, Cursor, VS Code, MCP Inspector e outros) não têm alguém para criar o app no painel. Por isso o servidor de autorização aceita dois registros automáticos, sem cadastro prévio:

Os dois geram um cliente público (PKCE, sem segredo) que já nasce Publicado, porém Não verificado: exibe o selo de aviso, mostra o domínio do redirect na tela de consentimento e só recebe escopos de identidade e leitura. A equipe Asender pode verificar um cliente, suspendê-lo ou bloquear um domínio (o bloqueio suspende os clientes registrados automaticamente naquele domínio e recusa novos). CIMD e DCR podem estar desligados em um ambiente; os metadados do servidor só anunciam o que está ligado.

Descoberta

curl -s https://auth.asender.net/.well-known/oauth-authorization-server

O documento (RFC 8414) traz, quando o recurso está ligado:

• registration_endpoint: https://auth.asender.net/register (DCR);
• client_id_metadata_document_supported: true (CIMD);
• token_endpoint_auth_methods_supported: client_secret_basic, client_secret_post e none;
• code_challenge_methods_supported: S256.

CIMD: a URL é o client_id

Publique um documento JSON em uma URL https estável (por exemplo https://app.exemplo.com/oauth/client.json) e use essa URL como client_id:

{
  "client_id": "https://app.exemplo.com/oauth/client.json",
  "client_name": "Meu agente",
  "client_uri": "https://app.exemplo.com",
  "logo_uri": "https://app.exemplo.com/logo.png",
  "redirect_uris": ["http://127.0.0.1/callback", "https://app.exemplo.com/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "openid profile email leads:read"
}

O que a Asender exige da URL e do documento:

• URL: https, porta 443, com caminho (não só /), sem usuário, sem fragmento (#), sem . ou .. no caminho, host com nome DNS (não IP) e até 2048 caracteres.
• Resposta: status 200, Content-Type: application/json, até 64 KiB, sem redirect, em até 5 segundos. A Asender não acessa endereços de rede interna.
• client_id do documento igual à URL, caractere a caractere.
• Sem client_secret (nem client_secret_expires_at) no documento.
• token_endpoint_auth_method ausente ou none; grant_types dentro de authorization_code e refresh_token; response_types só code.
• redirect_uris: de 1 a 10, https ou loopback, sem fragmento. Loopback casa qualquer porta.
• client_uri e logo_uri: https, se presentes. client_name perde caracteres de controle e é cortado em 100 caracteres.
• scope: o que passar de identidade e leitura é ignorado; omitido, vale todo o conjunto permitido a clientes não verificados.

Cache. A Asender guarda o documento conforme o Cache-Control: max-age da resposta, limitado entre 5 minutos e 24 horas (sem cabeçalho, 24 horas; no-store e no-cache valem 5 minutos). Se uma nova busca falhar por problema de rede, a cópia de até 7 dias é usada; um documento que ficou inválido nunca é aproveitado do cache. Se o documento não puder ser buscado ou validado, o /authorize responde invalid_client.

DCR: POST /register

curl -s https://auth.asender.net/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "Meu agente",
    "redirect_uris": ["http://127.0.0.1/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none",
    "scope": "openid profile email leads:read"
  }'

Resposta 201 Created:

{
  "client_id": "dcr_0123456789abcdef0123456789abcdef",
  "client_id_issued_at": 1792454400,
  "client_name": "Meu agente",
  "redirect_uris": ["http://127.0.0.1/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "openid profile email leads:read"
}

Campos aceitos no pedido: client_name, client_uri, logo_uri, redirect_uris (obrigatório), grant_types, response_types, token_endpoint_auth_method (só none) e scope. As regras são as mesmas do CIMD; campos desconhecidos são ignorados. Sem client_name, o nome vira o domínio do primeiro redirect. O corpo é JSON, com Content-Type: application/json, até 64 KiB.

• Sem client_secret: o cliente é sempre público e usa PKCE.
• Sem RFC 7592: a resposta não traz registration_access_token nem registration_client_uri; não há como ler, alterar ou apagar o registro depois. Se precisar mudar algo, registre outro cliente.
• Limite: 10 registros por hora por IP; acima disso, 429 com Retry-After.

Erros seguem a RFC 7591, no formato {"error", "error_description"}:

O parâmetro resource (RFC 8707)

O resource diz para qual API o token vale e define o aud do token. Os valores aceitos são:

• https://api.asender.net: a API REST pública;
• https://api.asender.net/mcp: o servidor MCP.

Envie-o no /authorize (o parâmetro pode se repetir). Qualquer outro valor é recusado com invalid_target: no /authorize, como error=invalid_target no redirect; no /token, como 400 com {"error":"invalid_target"}. No /token e no refresh você pode repetir resource com um subconjunto do que foi autorizado, para estreitar o aud do token; pedir algo que não foi autorizado também dá invalid_target. Sem resource, o token vale para https://api.asender.net.

Um token só do MCP não vale na API REST; veja o guia MCP.

Próximos passos

• O fluxo completo, com exemplo de código e tratamento de erros: Entrar com Asender.
• Conectar um agente de IA: Servidor MCP.
• Chave de API para a sua própria conta: Chaves de API.