How do I create a scoped Apify API token for ApifyForge?

Step-by-step

Step 1: Open console.apify.com/settings/integrations in a new tab and sign in to Apify.

Step 2: Click Create new token. Name it apifyforge-dashboard so you can identify it later in audit logs.

Step 3: Toggle Limit token permissions on. This is the critical step — without it you will create a full-access token that can do anything to your account. When you toggle it on, Apify reveals three permission dropdowns: Actors, Tasks, and Storages.

Step 4: Open the Actors dropdown and check exactly these three boxes:

✅ Read — list your actors and read metadata
✅ Run — trigger actor runs on your account
✅ List runs — read run history for analytics

Leave the rest (Build, List webhooks, Manage runs, Manage webhooks) unchecked.

Step 5: Leave the Tasks dropdown completely empty. ApifyForge does not use Apify Tasks.

Step 6: Open the Storages dropdown and check exactly these two boxes:

✅ Read — read dataset results returned by actor runs
✅ Write — let the token write to storages when making API calls

Leave Create unchecked.

Step 7: Scroll down to the Running Actors section. This controls what the backend actors ApifyForge triggers can do while they run on your account. Two settings need attention:

Make sure Restricted access is selected (not Full access). This should be the default once Limit token permissions is on.
Enable the Allow this token to access default run storages toggle.

Why this toggle matters: the scoped permissions above govern what the token can do via direct API calls, but this toggle governs what code running inside an actor started by the token can do with that run's default key-value store and dataset. Without it, the backend actors ApifyForge runs can't write their OUTPUT to their own default KV store — every run crashes at the save step. The toggle is separate from Storages: Write and both are required.

Step 8: Click Save. Apify displays the token once — it starts with apify_api_. Copy it immediately. You cannot retrieve it later; if you lose it, you will have to create a new one.

Step 9: Open ApifyForge Settings → Apify API Token, paste the token, and click Save. You should see a green "connected" indicator within a second or two. If the token is rejected, double-check you copied the full string without a trailing space.

What happens next

Open your ApifyForge dashboard. On a fresh account you will see a Get Fleet Health Score button. Click it. ApifyForge triggers the fleet-analytics backend actor on your account — the run takes about 2–3 minutes, and you can leave the page while it runs. When it finishes, the hero section re-renders with your Fleet Health Score, Action Plan, cost analysis, and the rest of your analytics.

Security note

Your token is encrypted with AES-256-GCM using a server-held key and stored in the ApifyForge PostgreSQL database. The encryption key lives only in the ApifyForge server environment — never in the database, never in logs, never in backups — so even a full database dump would yield ciphertext with no way to decrypt it.

You can revoke access at any time in two places:

In ApifyForge — Settings → Apify API Token → Delete token. Clears the encrypted value from the database.
In Apify — console.apify.com/settings/integrations, find apifyforge-dashboard, click Revoke. This invalidates the token everywhere and takes effect immediately, even if ApifyForge is unreachable. It is the definitive off switch.

For the full security and risk model — including what each permission actually grants, the destructive-capability disclosure on Storages: Write, blast radius if the token leaks, and the production hardening checklist for business-critical accounts — see What data can ApifyForge access?.

Common mistakes

If something is not working, check these first:

Forgot to toggle Limit token permissions — you created a full-access token by accident. Delete it in Apify and create a new one with the toggle on.
Forgot to enable "Allow this token to access default run storages" in the Running Actors section — backend actors triggered by the token can't write their OUTPUT to their own default key-value store, so every run crashes at the save step. This toggle is separate from Storages: Write and both are required. Rotate the token.
Missed Storages: Read — runs succeed but the dashboard shows nothing because the server cannot read the resulting dataset. You burn credits without seeing data. Rotate the token.
Missed Storages: Write — API-level writes fail. Rotate the token.
Checked Actors: Build — not needed. ApifyForge never triggers builds. Read-only build metadata is already granted by Actors: Read.
Checked anything under Tasks — not needed. ApifyForge does not use Apify Tasks at all. Leave the entire Tasks section empty.
Token was copied with a trailing space or newline — ApifyForge rejects it with a 401 when it validates against /v2/users/me. Re-copy cleanly.
Reused your main full-access token — defeats the purpose of scoped permissions. Always create a dedicated token named apifyforge-dashboard.

Frequently asked questions

Can I use my existing full-access token instead?

Technically yes, but you shouldn't. A full-access token can modify, delete, or rewrite anything in your Apify account — if it leaks, the attacker has full control. A scoped token with only the five permissions above limits the blast radius to "can read storages and trigger runs," which is dramatically less dangerous. Creating a scoped token takes 2 minutes and is worth the peace of mind.

What if I accidentally grant too many permissions?

Apify does not let you edit a token's permissions after creation — the scope is locked at create time. Delete the token in Apify, create a new one with the correct scope, and paste that into ApifyForge Settings. The new token automatically overwrites the old one; you do not need to delete the old one from ApifyForge first.

Does the token expire?

Not unless you set an expiration. As a best practice, rotate every 90 days for regular accounts and every 30 days for business-critical production accounts. Create a new scoped token, paste it into Settings, then revoke the old one in Apify. Full rotation guidance is in What data can ApifyForge access? → Production hardening.

Can I use the CLI instead of pasting a token into the browser?

Yes. Run npx apifyforge run <tool> in your terminal with APIFY_TOKEN set in your local environment. The CLI uses your token locally, calls the Apify API directly, and uploads only the computed analytics to your dashboard — nothing is stored on ApifyForge's servers. Both the browser flow and the CLI flow produce identical results in the dashboard. The CLI is the recommended option if your Apify account contains highly sensitive data.

Learn more

What data can ApifyForge access? — the full security reference. What each permission grants, how the blast radius is bounded, the destructive-capability disclosure on Storages: Write, the scoped-vs-full-access comparison, GDPR guidance, decision framing for high-stakes accounts, and the production hardening checklist.
Do you store my API token? — how the token is encrypted at rest and what revocation actually does on both the ApifyForge and Apify side.
How do I connect my Apify account? — the broader OAuth sign-in + token setup flow for new users.
How do I disconnect my account? — how to revoke ApifyForge's access cleanly when you're done.

Last updated: April 14, 2026