Chaves de API e escopos

Como criar, escopar, girar e revogar chaves de API (sk_live_ e sk_test_), e quais escopos cada rota exige.

Chaves de API

A chave de API é a credencial que o seu servidor usa para falar com a API da Asender: enviar e-mail, SMS, push e WhatsApp, e ler os dados da sua conta. Este guia mostra como criar e usar uma chave, quais escopos existem, como mantê-la segura e quando, em vez de uma chave, você deve usar um app OAuth.

• Base da API: https://api.asender.net
• Formato: sk_live_… ou sk_test_…, enviada em Authorization: Bearer
• Onde criar: painel de administração da conta, em Chaves de API

Chave de API ou app OAuth: qual usar

Regra prática: se o código roda no seu servidor e age na sua conta (disparar um código de verificação, importar relatórios para o seu BI), use chave de API. Se você vai oferecer um produto que outras pessoas conectam à conta delas, use app OAuth: veja o guia Entrar com Asender. Não distribua a sua chave a clientes seus para "conectarem" a conta deles; é o caso de uso do app OAuth.

Criar uma chave

1. Entre no painel de administração da conta (https://admin.asender.net/t/<conta>/api-keys). Criar, editar e revogar chaves exige permissão de administração da conta.
2. Dê um nome que diga onde a chave é usada (por exemplo site-checkout).
3. Escolha o modo (live ou test; veja abaixo) e marque só os escopos de que a integração precisa. Nasce marcado apenas email:send.
4. Clique em Criar chave. O segredo completo aparece uma única vez: copie e guarde num cofre ou no gerenciador de segredos do seu servidor. A Asender guarda só um hash; se você perder, revogue e crie outra.

Depois disso a lista mostra, para cada chave, o nome, o prefixo (por exemplo sk_live_ab12, só para você reconhecê-la), o modo, os escopos, a data de criação e o último uso (data e IP de origem).

Quem automatiza a emissão pode usar a API de sessão da plataforma (POST https://api.asender.net/api/tenants/{id}/api-keys, com name, scopes e opcionalmente mode); veja o guia da API Platform.

Usar a chave

curl -X POST 'https://api.asender.net/v1/emails/send' \
  -H "Authorization: Bearer $ASENDER_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pedido-1042-confirmacao' \
  -d '{
    "Source": "contato@empresa.com.br",
    "Destination": { "ToAddresses": ["cliente@exemplo.test"] },
    "Message": { "Subject": { "Data": "Pedido confirmado" }, "Body": { "Text": { "Data": "Obrigado!" } } }
  }'

A mesma chave vale nas APIs de produto (por exemplo api.mail.asender.net, api.pages.asender.net), conforme os escopos. Só o header Authorization: Bearer é aceito; X-Api-Key e ?api_key= respondem 401.

Escopos

Todo escopo tem o formato <recurso>:<ação>. Chave sem escopo não funciona: a emissão sem escopos, ou com um valor fora desta tabela, é recusada com 400 (a resposta traz a lista válida), e uma chave antiga sem escopo do catálogo recebe 403 InsufficientScope em toda rota. Cada rota exige exatamente um escopo.

Envio

Leitura

Administração e conteúdo

GET /v1/account (dados básicos da conta) aceita qualquer chave válida. O detalhe rota a rota está no guia da API Platform.

Painel e catálogo. A API aceita os 28 escopos acima na emissão. Hoje a tela de criação do painel ainda não lista os escopos de canal não oficial (telegram:send, whatsweb:send, telegramconta:send); para uma chave com eles, emita pela API de sessão (POST /api/tenants/{id}/api-keys), com o escopo no corpo.

Boas práticas

• Uma chave por integração. Se uma vazar, você revoga só ela, sem derrubar o resto. O nome da chave e o "último uso" mostram qual integração é qual.
• O mínimo de escopos. Um serviço que só dispara códigos de verificação precisa de email:send e nada mais. Uma chave de relatórios não deve ter *:send. Escopos de leitura e de envio raramente pertencem à mesma chave.
• Só no servidor. Nunca em JavaScript de navegador, em app mobile, em repositório, em log, em tela ou em chat. O que vai para o navegador não é segredo. As rotas de envio de push, WhatsApp, Telegram e canais não oficiais recusam chave de servidor usada de um navegador (403 ServerKeyInBrowser).
• Variável de ambiente ou cofre. Leia de ASENDER_API_KEY (ou do gerenciador de segredos), nunca do código-fonte. Não imprima a chave em log de erro.
• Rotação. Crie a chave nova, publique-a no seu ambiente, confirme o tráfego pelo "último uso" e revogue a antiga. Faça isso em intervalos regulares e sempre que alguém com acesso sair da equipe.
• Idempotência nos envios. Mande Idempotency-Key em todo envio que pode ser repetido por retry, para um retry não duplicar a mensagem nem a cobrança.
• Respeite o rate limit. O teto padrão é de 100 requisições por segundo, por chave; em 429, espere o Retry-After. Veja o guia da API Platform.
• Audite pelo log. Com logs:read, GET /v1/logs mostra o que cada chave mandou e o que a API respondeu, com segredos e conteúdo redigidos.

Revogar e alterar

Na lista de chaves, Revogar invalida a chave. Também é possível renomear uma chave e trocar os seus escopos sem mudar o segredo. Como a API guarda a validação em cache por pouco tempo, uma revogação ou troca de escopos passa a valer em até 60 segundos. Depois disso a chave revogada recebe 401.

Se você suspeita de vazamento: revogue primeiro, investigue depois (o log da API e o "último uso" dizem de onde veio o tráfego) e emita uma chave nova.

Live e test

Ao criar a chave você escolhe o modo: produção (sk_live_…, o padrão) ou teste (sk_test_…). Hoje a diferença é só o rótulo: o modo aparece no painel e nos logs da API (filtro mode), e serve para separar o tráfego de desenvolvimento do de produção. Não existe sandbox: uma chave sk_test_ tem os mesmos escopos e o mesmo rate limit, e a API não trata o envio feito com ela de forma diferente. Não use uma chave de teste para "ensaiar" envio a clientes reais. Um sandbox de verdade é planejado.

Chave pública de site (pk_push_)

Para registrar visitantes do seu site para web push, o navegador não pode usar uma chave sk_…. Existe uma chave própria para isso:

• formato pk_push_…, pública (vai no HTML do site, no snippet de push);
• é gerada no painel, na tela de push, junto do manifest.json, do service worker e do snippet já preenchidos, e fica atrelada às origens do site que você declara;
• só abre uma rota, POST /v1/push/site/devices, que registra a inscrição de web push do visitante. Não envia nada, não lê nada;
• é limitada por volume (por IP e por chave), porque, como toda chave de navegador, ela pode ser vista por qualquer visitante.

Ela não substitui a chave de API: para enviar o push, o seu servidor usa uma chave sk_… com push:send. Veja o guia do navegador e a API Platform.

Erros comuns

Próximos passos

• API Platform: todas as rotas, escopos e erros.
• Entrar com Asender: apps que agem em nome de usuários de outras contas.
• Aplicativos: cadastrar e publicar o seu app OAuth no painel.
• Webhooks: receber eventos em vez de consultar.
• Servidor MCP, em https://api.asender.net/mcp: veja o guia MCP.