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

To create a scoped Apify API token for ApifyForge, open console.apify.com/settings/integrations, click Create new token, toggle Limit token permissions, and enable only the five permissions ApifyForge needs: Actors (Read, Run), Actor runs (Read), Actor builds (Read), Datasets (Read), and Key-value stores (Read, Write). Copy the apify_api_... token and paste it into ApifyForge Settings → Apify API Token. The whole process takes about two minutes.

Why a scoped token (not your full-access token)

Apify tokens can either be full-access — meaning they can create, modify, run, and delete anything in your account — or scoped with granular permissions. For ApifyForge, you should always create a scoped token. A scoped token limits the blast radius: even in the worst case (a compromised ApifyForge database, a leaked token, a malicious browser extension), an attacker with your scoped token cannot modify your actor source code, cannot delete your datasets, and cannot change your billing. They can only read metadata and trigger runs, which is exactly what ApifyForge needs and nothing more.

Apify also explicitly blocks scoped tokens from modifying Actor source regardless of permissions, which gives you an additional layer of protection: your actor code is safe even if every other safeguard fails.

Step-by-step: creating the token

Step 1: Sign in to your Apify account and open the API & Integrations page at console.apify.com/settings/integrations. This is where Apify lists all your existing tokens and integrations.

Step 2: Click the Create new token button. A dialog appears asking for a token name and permissions. Give it a descriptive name like apifyforge-dashboard so you can identify it later in audit logs — avoid generic names like token1 or test, which become meaningless when you have multiple integrations.

Step 3: Toggle the Limit token permissions switch. This is the key step — without it you will end up with a full-access token that can do anything to your account. When you toggle it on, Apify reveals a permission matrix with rows for each resource type (Actors, Actor runs, Actor builds, Datasets, Key-value stores, Request queues, Schedules, Proxy, etc.) and columns for actions (Read, Write, Run, Delete).

Step 4: Check exactly these five permissions and nothing else:

• Actors — Read, Run
• Actor runs — Read
• Actor builds — Read
• Datasets — Read
• Key-value stores — Read, Write

Leave everything else unchecked. In particular, do NOT grant Write access to Actors — that would let a compromised token rewrite your actor source. Do NOT grant Delete on anything. Do NOT enable Request queues, Schedules, Proxy, or Webhooks. ApifyForge does not need any of these, and a narrower token is a safer token.

Step 5: Click Save. Apify generates the token and shows it to you once. The token starts with apify_api_ followed by a long random string. Copy it immediately — you cannot retrieve it again after closing the dialog. If you lose it, you have to create a new one.

Step 6: Open ApifyForge in another tab, go to Settings → Apify API Token, paste the token into the input field, and click Save token. ApifyForge validates the token by calling Apify's /v2/users/me endpoint — if the token is valid, the dashboard shows a green "connected" indicator. If it is rejected, Apify will return a 401 and ApifyForge will show an error; double-check you copied the full token without a trailing space.

Why exactly these five permissions

Each permission corresponds to something specific that the ApifyForge backend actors need to do when they run on your account:

• Actors: Read — list your actors so the dashboard can show what is in your fleet and which actors each analytics run should cover.
• Actors: Run — invoke actors on your account. This is what triggers a fresh fleet-analytics run, compliance scan, schema validation, etc. when you click Run in the dashboard.
• Actor runs: Read — fetch run history, duration, memory consumption, and status for each actor. This powers the reliability, failure rate, and cost calculations.
• Actor builds: Read — check which build each actor is currently using so the release-gate and schema-validator can reason about what changed between versions.
• Datasets: Read — inspect dataset metadata (item counts, schemas) so output-completeness and quality analytics can compute their scores. The actual dataset contents are never copied to ApifyForge — only the shape and size.
• Key-value stores: Read, Write — read the SIGNALS key that each backend specialist writes at the end of its run, and write trend snapshots so week-over-week comparisons work. Read alone is not enough, because trend tracking requires writing the previous state back.

If any of these permissions is missing, the corresponding feature will fail. For example, if you forget Actors: Run, the dashboard will load cached data fine but clicking Run will return a 403 from the Apify API.

How ApifyForge stores and protects your token

Once you paste the token into Settings, ApifyForge encrypts it with AES-256-GCM using a server-held key before writing it to the database. The key lives only in the ApifyForge server environment (not in the database), so even a full database dump would yield ciphertext with no way to decrypt it. When an analytics run needs to talk to Apify, the server decrypts the token in memory, makes the API call, and never persists the plaintext.

You can revoke access at any time in two places: delete the token in ApifyForge Settings (this clears the encrypted value from our database), or revoke the token from console.apify.com/settings/integrations in Apify itself (this invalidates it everywhere). Revoking in Apify is the definitive off switch — it works even if ApifyForge is unreachable.

For a full rundown of the security model, see Do you store my API token?.

Frequently asked questions

Can I use my existing full-access token instead?

Technically yes, but you should not. A full-access token can modify, delete, or rewrite anything in your Apify account. If it leaks — from any source, not just ApifyForge — the attacker has full control. A scoped token with only the five permissions above limits the damage to "can read metadata and trigger runs," which is dramatically less dangerous. Creating a scoped token takes about two minutes and is worth the peace of mind.

What if I accidentally grant too many permissions?

Delete the token in Apify and create a new one with the correct scope. Apify does not let you edit an existing token's permissions after creation — the permission set is fixed at create time — so the only fix is to rotate. ApifyForge will detect the new token when you paste it into Settings.

Does the token expire?

Apify tokens do not expire automatically unless you set an expiration when creating them. As a best practice, we recommend rotating every 90 days: create a new scoped token, paste it into ApifyForge Settings (which overwrites the old one), then revoke the old token in Apify. If you suspect any kind of compromise, rotate immediately.

Can I still use the CLI instead of the API token flow?

Yes. ApifyForge supports both modes. The browser-based API token flow (this page) is the easiest for most users — you paste one token and the dashboard runs everything on your account automatically. The CLI flow (npx apifyforge run <tool>) is available under Settings → Advanced for users who prefer to keep their token entirely on their own machine and never store it server-side. Both modes produce identical results in the dashboard.

Why does ApifyForge need Write access to Key-value stores?

The backend specialists write a SIGNALS key at the end of each run so the fleet-analytics orchestrator can collect cross-specialist signals in one place, and the orchestrator writes trend snapshots so next week's run can compute deltas. Without Write access on key-value stores, trend tracking and fleet health scoring would not work. Write access is scoped to key-value stores only — it does NOT give ApifyForge the ability to modify datasets, actors, or builds.

Last updated: April 12, 2026