Permissions

Copy for LLM

Learn how to declare and manage permissions for your Actor, what permission levels mean, and how to build secure, trusted Actors for Apify users.

---

Every time a user runs your Actor, it runs under their Apify account. Actor permissions define the level of access your Actor needs to run. This gives users transparency and control over what data your Actor can access, building trust in your tools.

Your Actors can request two levels of access:

• Limited permissions: Actors with this permission level have restricted access, primarily to their own storages and the data they generate. They cannot access other user data on the Apify platform.
• Full permissions: This level grants an Actor access to all of a user's Apify account data.

Most Actors should use limited permissions to request only the specific access they need and reserve full permissions for exceptional cases where the Actor cannot function otherwise.

How Actor permissions work

When a user runs an Actor, it receives an Apify API token. This token is injected to the Actor's runtime and has a scope of access as requested by the Actor's permission level.

Actors with Full permissions receive a token that grants complete access to the user's Apify account via the Apify API.

Actors with Limited permissions receive a restricted scoped token. This token only allows the Actor to perform a specific set of actions, which covers the vast majority of common use cases.

A limited-permission Actor can:

• Read and write to its default storages.
• Create any additional storage, and write to that storage.
• Read and write to storages created in previous runs.
• Update the current run's status or abort the run.
• Metamorph to another Actor with limited permissions.
• Read and write to storages provided via Actor input (for example, when the user provides a dataset that the Actor should write into).
• Read basic user information from the environment (whether the user is paying, their proxy password, or public profile).
• Run any other Actor with limited permissions.

This approach ensures your Actor has everything it needs to function while protecting user data from unnecessary exposure.

Migrating to limited permissions

To learn how to migrate your Actors to run under limited permissions, check out the Migration guide

Configuring Actor permissions level

You can set the permission level for your Actor in the Apify Console under its Settings tab. All the existing Actors are configured to use full permissions.

End-user experience

Users see a visible permission badge on your Actor's detail page indicating whether it requires Limited permissions or Full permissions. The experience of running an Actor remains the same for users.

Impact on Actor Quality score

When possible, design your Actors to use limited permissions and request only the access they truly need. Actors requiring full permissions may receive a lower Actor Quality score, which can reduce their ranking in the store.

Accessing user provided storages

By default, limited-permissions Actors can't access user storages. However, they can access storages that users explicitly provide via the Actor input. To do so, use the input schema to add a storage picker and declare exactly which operations your Actor needs.

• Add a field with editor: "resourcePicker".
• Set resourceType to one of dataset, keyValueStore, or requestQueue.
• Specify resourcePermissions with the minimal required scope: "READ" or "READ", "WRITE".

Actors running under full permissions are assumed to have full (i.e. read/write/manage) access to user storages. In that case the resourcePermissions field does not have to be set.

Example input schema field (single resource):

{
  "title": "Output dataset",
  "type": "string",
  "editor": "resourcePicker",
  "resourceType": "dataset",
  "resourcePermissions": ["READ", "WRITE"]
}

Selecting multiple resources:

• Use type: "array" to let users choose more than one storage.
• Each selected resource will have the same resourcePermissions

{
  "title": "Source datasets",
  "type": "array",
  "editor": "resourcePicker",
  "resourceType": "dataset",
  "resourcePermissions": ["READ"],
  "minItems": 1
}

Behavior at run time:

• The user’s selection is injected into the run input, and the run token is expanded to allow only the requested operations on the selected storages.
• If your code attempts an operation not covered by resourcePermissions (for example, writing with only READ), the platform returns an insufficient-permissions error.

See the full input schema reference for details..

Requesting full permissions

Designing your Actors to work under limited permissions is the recommended approach, it helps improve your Actor Quality score and increases user trust and adoption. However, some use cases do legitimately require broader access to user data (e.g., to perform administrative tasks or orchestrate other Actors). If your Actor falls in this category or cannot function with limited permissions for another reason:

• Explain why you need full permissions in your Actor's README. This will help keep user trust and set correct user expectations.
• Set the permission level in the Actor’s Settings in Console to Full permissions.
• Be aware of the UX implications and impact on Actor Quality score for full-permission Actors.

Need help with Actor permissions?

If you cannot migrate to limited permissions or have a use case that should work under limited permissions but does not, contact support or ask on the community forum.