Autenticação

As chaves publishable podem ser embebidas em HTML ou em bundles mobile. As chaves secret ficam do lado do servidor e assinam a entrega server-to-server — a montagem de áudio e a preparação de e-mail. Para gerir campanhas, anúncios e relatórios a partir do seu sistema existem as chaves de integração (ak_), com âmbitos explícitos; o painel usa a sessão da conta.

Chaves de teste não consomem orçamento nem contam para a facturação. Usa-as em CI e em staging. Chaves live exigem subscrição activa e propriedade verificada.

Para o seu sistema criar campanhas e anúncios sem abrir o painel. Cria-se a chave em Definições › Chaves, escolhe-se o que ela pode fazer e usa-se como bearer. O segredo é mostrado uma única vez.

curl -X POST https://api.adpluga.com/v1/campaigns \
  -H 'Authorization: Bearer ak_live_•••' \
  -H 'Idempotency-Key: 8f3a…' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Outono","objective":"traffic","pricing_model":"CPM","bid_cents":200,"pacing":"uniforme"}'

Os âmbitos disponíveis são campaign:read, campaign:write, ad:read, ad:write, asset:read, asset:write, property:read e reports:read. Três limites que convém conhecer antes de desenhar a integração:

• A chave só alcança os endpoints cobertos pelos seus âmbitos. Facturação, carteira, pagamentos, membros e a gestão de chaves respondem 403 a qualquer chave, sejam quais forem os âmbitos.
• Uma chave age como quem a criou: se essa pessoa perder uma permissão ou sair da conta, a chave perde-a também. Emita-a a partir de um utilizador com o papel que a integração deve ter, não do dono da conta.
• O prefixo decide o ambiente. Uma ak_test_ escreve em modo de teste — não cobra e não conta para as métricas — e é com ela que se desenvolve; ak_live_ escreve a sério.

Se não quer que a sua equipa troque de aplicação para criar campanhas, abra o ecrã da adPluga dentro da sua própria interface. O seu servidor pede uma sessão com a chave de integração; o browser abre-a num diálogo. Ninguém faz login dentro da janela — a sessão já vem autenticada.

curl -X POST https://api.adpluga.com/v1/embed/sessions \
  -H 'Authorization: Bearer ak_live_•••' \
  -H 'Content-Type: application/json' \
  -d '{"component":"campaign_create","origin":"https://admin.suaempresa.com"}'

# -> { "client_secret": "cs_•••", "url": "https://api.adpluga.com/embed/campanha/?cs=cs_•••", "expires_at": "…" }

• O segredo é de uso único e dura 5 minutos. Peça-o no momento em que a pessoa carrega no botão, não no carregamento da página.
• A página só aceita ser enquadrada pela origem que indicou. Uma origem diferente é recusada pelo browser, não por nós.
• O que o ecrã pode fazer é o que a chave já podia: uma chave ak_test_ escreve em modo de teste e não há cabeçalho que a mude.

Roda a partir do dashboard ou via API. A chave anterior é revogada imediatamente; rode antes do deploy para evitar downtime.

curl -X POST https://api.adpluga.com/v1/sdk-keys/{id}/rotate \
  -H 'Authorization: Bearer SEU_ACCESS_TOKEN'

Envia a chave publishable como X-AdPluga-Key ao chamar /v1/serve do browser. A chave secret viaja em Authorization: Bearer sk_… nos endpoints server-to-server que a aceitam. Nunca exponhas chaves secret no cliente.

Trata as chaves secret como passwords. O princípio é o mesmo de qualquer credencial sensível: nunca a colocar em código, nunca a registar em logs, separar cada ambiente.

• Nunca faças commit de chaves sk_… para git. Usa ficheiros .env protegidos por .gitignore, secrets do GitHub Actions ou um secret manager (AWS Secrets Manager, Vault, Doppler).
• Roda chaves a cada 90 dias e imediatamente se uma chave aparecer em logs, artefactos de build ou em ferramentas de terceiros.
• Mantém chaves de teste e live em contas e ambientes separados. Uma pk_test_ exposta é um não-evento; uma sk_live_ exposta é um incidente de segurança.
• Cada propriedade tem as suas chaves. Para isolar um integrador, dá-lhe uma propriedade e as chaves dela em vez de partilhares a sk_live_ de outra.

Cada resposta /v1/serve devolve um track_token assinado com o segredo da propriedade e com TTL do lado do servidor. Os payloads POST /v1/track têm de repetir o token verbatim — a edge valida a assinatura, rejeita replays fora do TTL e liga o evento à propriedade e ao slot certos.

curl -X POST https://edge.adpluga.com/v1/track \
  -H 'Content-Type: application/json' \
  -H 'X-AdPluga-Key: pk_test_•••' \
  -d '{"token":"eyJ…","event":"click"}'

Cada token é de uso único dentro do TTL (10 minutos por defeito). Repetir o mesmo token devolve 204 e não conta duas vezes — o retry é seguro.

Os erros de autenticação partilham o envelope { error: { code, message } }. Os códigos mais comuns:

Antes de mudar para pk_live_… numa propriedade real:

• Verifica a propriedade no dashboard (validação por DNS ou HTML-tag) — propriedades não verificadas não servem tráfego live.
• Troca pk_test_… por pk_live_… no pipeline de build, não no código — usa variáveis de ambiente.
• Monitoriza /integration/status e /integration/events na primeira hora após o rollout; o dashboard expõe ambos.
• Acompanha o saldo e o consumo em Facturação: uma campanha em teste não gasta, mas uma campanha live com um bug de integração gasta.
• Sonda /v1/integration/status e /v1/integration/events a partir do teu sistema. Não há webhooks de saída — quando existirem, ficam documentados aqui.