Apify Security Basics
Overview
Security best practices for Apify API tokens, Actor data, proxy credentials, and webhook verification. Apify uses personal API tokens (prefixed apify_api_) for all authentication. Because a single token grants full account access with no per-token scoping, token hygiene is the whole game.
Prerequisites
- Apify account with Console access
- Understanding of environment variables
- Access to your deployment platform's secrets management
Token Architecture
Apify uses a single API token per user account for full API access. There is no scope-based permission system per token, so token security is critical.
| Token Type | Format | Where to Find |
|---|
| Personal API token | apify_api_... | Console > Settings > Integrations |
| Proxy password | Alphanumeric | Console > Proxy > Connection settings |
Instructions
Follow the six hardening steps in order. Each has a lean summary below; the full
copy-paste code for every step is in
references/implementation.md.
-
Secure token storage — keep the token in .env (never hardcoded) and add
.env, .env.*.local, and storage/ to .gitignore. Validate presence at
startup so the app fails fast:
function requireToken(): string {
const token = process.env.APIFY_TOKEN;
if (!token) throw new Error('APIFY_TOKEN is required');
if (!token.startsWith('apify_api_')) console.warn('unexpected token prefix');
return token;
}
-
Per-environment token isolation — separate tokens (ideally separate
accounts) for dev / staging / prod, injected via each platform's secret store
(gh secret set, vercel env add, GCP Secret Manager).
-
Token rotation — generate the new token first (old stays valid), push to
every environment, verify it authenticates, then revoke the old one.
-
Webhook payload verification — Apify does not sign webhooks; confirm the
run ID in the payload actually exists, or gate on a shared URL secret compared
with crypto.timingSafeEqual.
-
Actor data security — redact sensitive fields before pushData; keep
datasets named and private (no public sharing).
-
Proxy security — never log proxyConfig.newUrl() (it embeds the proxy
password); log the proxy group only.
See references/implementation.md for the complete
code of every step, and references/examples.md for
end-to-end scenarios.
Output
Applying this skill produces a hardened project state:
- A
.gitignore that excludes .env* and storage/, with no token in the tree.
- A startup token validator that throws on a missing/malformed
APIFY_TOKEN.
- Environment-specific tokens wired into each platform's secret store.
- A documented rotation procedure and a completed Security Checklist (below).
- Webhook handlers that reject unverified runs and pipelines that redact PII
before storage.
Security Checklist
Leaked Token Response
If a token is exposed:
- Immediately regenerate token in Console > Settings > Integrations
- Check recent Actor runs for unauthorized usage
- Review billing for unexpected charges
- Rotate proxy password if exposed
- Audit git history:
git log --all -p -- '*.env' '*.json' | grep apify_api_
Error Handling
| Issue | Detection | Mitigation |
|---|
| Token in git history | git log -p | grep apify_api_ | Rotate token, use BFG to clean |
| Unauthorized runs | Unexpected runs in Console | Rotate token immediately |
| Proxy password exposed | Credentials in logs | Regenerate proxy password |
| Data breach in dataset | PII in public dataset | Delete dataset, sanitize pipeline |
Examples
Quick starting point — bootstrap a new project's secrets safely:
cat >> .gitignore <<'EOF'
.env
.env.*.local
storage/
EOF
echo 'APIFY_TOKEN=apify_api_dev_token' > .env
git status --short
Four full worked scenarios — secure bootstrap, cross-environment rotation,
webhook-verify-then-sanitize, and a git-history leak audit — are in
references/examples.md.
Resources
Next Steps
For production deployment hardening beyond secrets — health checks, rate limits,
and monitoring — see the apify-prod-checklist skill in this pack.
