Autenticação
Autenticação
O adPluga usa chaves publishable no cliente e chaves secret no servidor. Cada chave está limitada a uma propriedade e a um ambiente — teste ou live.
Formatos de chave
As chaves publishable podem ser embebidas em HTML ou em bundles mobile. As chaves secret têm de ficar do lado do servidor: podem gerir campanhas, ler relatórios e rodar chaves.
| Prefix | Usage | Scope |
|---|---|---|
| pk_test_… | client | Test env, safe to embed |
| pk_live_… | client | Production, safe to embed |
| sk_test_… | server | Server-only. Test env. |
| sk_live_… | server | Server-only. Production. |
Teste vs live
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.
Rotação de chaves
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 sk_live_•••'CORS e cabeçalhos
Envia a chave publishable como X-AdPluga-Key ao chamar /v1/serve do browser. As chaves secret viajam em Authorization: Bearer sk_…. Nunca exponhas chaves secret no cliente.
Armazenamento e rotação
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.
- Se um integrador precisar de acesso só-leitura, emite uma chave dedicada com o role integrator em vez de partilhares a sk_live_.
Tokens de tracking (HMAC)
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 '{"track_token":"eyJ…","event":"click"}'Cada track_token é de uso único dentro do TTL (10 minutos por defeito). Reutilizar devolve 409.
Códigos de erro
Os erros de autenticação partilham o envelope { error: { code, message } }. Os códigos mais comuns:
| Status | Código | Quando |
|---|---|---|
| 401 | missing_key | Falta o header X-AdPluga-Key ou o bearer Authorization. |
| 401 | invalid_key | Chave malformada ou sem correspondência a uma propriedade conhecida. |
| 403 | key_revoked | Chave foi rodada ou revogada manualmente no dashboard. |
| 403 | tenant_suspended | Subscrição do tenant expirada, pagamento falhado ou conta pausada. |
| 403 | wrong_environment | Chamar /v1/serve com pk_test_… contra a edge live ou vice-versa. |
| 429 | rate_limited | Throughput por chave ou por IP excedido. Respeita o header Retry-After. |
Checklist de produção
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.
- Define um alerta de orçamento na carteira para que um bug de integração não esgote a conta em silêncio.
- Configura um webhook (ou proxy) para billing.invoice.failed e key.rotated para acordar a equipa certa.