Authentication

adPluga uses publishable keys on the client and secret keys on the server. Every key is scoped to a property and to an environment — test or live.

Key formats

Publishable keys are safe to embed in HTML or mobile bundles. Secret keys must stay server-side: they can manage campaigns, read reports and rotate keys.

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.

Test vs live

Test keys never spend budget and never count toward billing. Use them in CI and in staging. Live keys require an active subscription and a verified property.

Rotating a key

Rotate from the dashboard or via API. The previous key is revoked immediately; rotate before deploying the new one to avoid downtime.

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

CORS and headers

Send the publishable key as X-AdPluga-Key when calling /v1/serve from the browser. Secret keys travel as Authorization: Bearer sk_…. Never expose secret keys client-side.

Storage and rotation

Treat secret keys like passwords. The principle is the same as any sensitive credential: never check them in, never log them, scope every deployment to its own key.

Never commit sk_… keys to git. Use .gitignore-protected .env files, GitHub Actions secrets or a secret manager (AWS Secrets Manager, Vault, Doppler).
Rotate at least every 90 days and immediately if a key was exposed in logs, build artefacts or a third-party tool.
Keep test and live keys in separate accounts and separate environments. A leaked pk_test_ is a non-event; a leaked sk_live_ is a security incident.
If an integrator needs read-only access, issue a dedicated key with the integrator role instead of sharing your sk_live_.

Tracking tokens (HMAC)

Every /v1/serve response returns a track_token signed with the property's shared secret and a server-side TTL. POST /v1/track payloads must replay that token verbatim — the edge validates the signature, rejects replays beyond the TTL and binds the event to the correct property and slot.

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"}'

track_tokens are single-use within the TTL (10 minutes by default). Reusing one yields 409.

Error codes

Authentication errors share the standard envelope { error: { code, message } }. The most common codes:

Status	Code	When
401	missing_key	X-AdPluga-Key header or Authorization bearer is missing.
401	invalid_key	Key does not match a known property or is malformed.
403	key_revoked	Key was rotated or manually revoked from the dashboard.
403	tenant_suspended	Tenant subscription expired, billing failed or the account was paused.
403	wrong_environment	Calling /v1/serve with pk_test_… against the live edge or vice-versa.
429	rate_limited	Per-key or per-IP throughput exceeded. Back off using the Retry-After header.

Production checklist

Before flipping the switch to pk_live_… on a real property:

Verify the property in the dashboard (DNS or HTML-tag check) — unverified properties cannot serve live traffic.
Swap pk_test_… for pk_live_… in your build pipeline, not in source — use environment variables.
Monitor /integration/status and /integration/events for the first hour after rollout; the dashboard surfaces both.
Set a wallet budget alert so an integration bug cannot drain the account silently.
Wire a webhook (or webhook proxy) for billing.invoice.failed and key.rotated so the right team is paged.