feat: Public Actor Permissions

sources/platform/actors/development/actor_definition/input_schema/specification.md

@@ -861,7 +861,8 @@
     "title": "Datasets",
     "type": "array",
     "description": "Select multiple datasets",
-    "resourceType": "dataset"
+    "resourceType": "dataset",
+    "resourcePermissions": ["READ"]
 }
 ```
 
@@ -876,5 +877,18 @@
 | `type`         | One of <ul><li>`string`</li><li>`array`</li></ul>                                 | Yes      | Specifies the type of input - string for single value or array for multiple values |
 | `editor`       | One of <ul><li>`resourcePicker`</li><li>`hidden`</li></ul>                        | No       | Visual editor used for <br/>the input field. Defaults to `resourcePicker`.         |
 | `resourceType` | One of <ul><li>`dataset`</li><li>`keyValueStore`</li><li>`requestQueue`</li></ul> | Yes      | Type of Apify Platform resource                                                    |
+| `resourcePermissions` | Array of strings; allowed values: <ul><li>`READ`</li><li>`WRITE`</li></ul> | Yes | Permissions requested for the referenced resource(s). Use [\"READ\"] for read-only access, or [\"READ\", \"WRITE\"] to allow writes. Applies to each selected resource (for `type: array`). |
 | `minItems`     | Integer                                                                           | No       | Minimum number of items the array can contain. Only for `type: array`              |
 | `maxItems`     | Integer                                                                           | No       | Maximum number of items the array can contain. Only for `type: array`              |
+
+### Resource permissions
+
+The `resourcePermissions` field expresses **what operations your Actor needs on the user-selected storage(s)**. It is evaluated at run start and used to expand a [Limited-permissions Actor's](../../permissions/index.md#) scope to be able to access the resource sent via Actor's input.
+
+- `["READ"]` — the Actor may read from the referenced resource(s).
+- `["READ", "WRITE"]` — the Actor may read and write to the referenced resource(s).
+
+Notes:
+- This setting does not change field visibility or it being required in the UI; it only defines runtime access for the selected resource(s).
+- For array fields (`type: array`), the same permissions apply to **each** selected resource.
+- If your Actor attempts an operation without the requested permission (e.g., attempts to write with a read-only access), the run will fail with an insufficient-permissions error.

sources/platform/actors/development/permissions/index.md

@@ -0,0 +1,60 @@
+---
+title: Permissions
+description: Learn how to declare and manage permissions for your Actor, what access levels mean, and how to build secure, trusted Actors for Apify users.
+sidebar_position: 7.5
+slug: /actors/development/permissions
+---
+
+**Learn how to declare and manage permissions for your Actor, what access 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** is an Actor level setting that defines the level of access your Actor needs to be able to run. This gives users transparency and control over what data your Actor can access, building trust in your tools.
+
+There are two levels of access your Actors can request:
+- **Limited permissions (preferred):**  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
+
+## 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 permission level.
+
+Actors with **full permissions** receive a token with full access to the users account, this token grants access to the user's entire Apify account via Apify API.
+
+Actors with **limited permissions** receive [a restricted scoped token](link). 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.
+- Update the current run’s status, abort the run, or metamorph to another Actor (as long as it also has limited permissions).
+- Read basic user information (whether the user is paying, proxy password, public profile).
+- Read or also write to storages provided via Actor input (sample scenario: the user provides the Actor with a dataset that the Actor should write into).
+- Run any other Actor with limited permissions.
+- Create any additional storage, and write to that storage.
+- Read and write to storages created in previous runs.
+
+This approach ensures your Actor has everything it needs to function while protecting user data from unnecessary exposure.
+
+### Accessing user provided storages
+
+TODO: a section detailing how a limited permission actor can expand its scope
+
+### Declaring permissions
+
+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, but the plan is to make limited permissions the default for all new Actors.
+
+![Actor permissions configuration in Actor settings](./images/actor_settings_permissions.webp)
+
+### End-user experience
+
+Initially, users will begin to see a gray, muted badge on your Actor's detail page indicating whether it requires "Limited permissions" or "Full permissions". At this stage, the experience of running an Actor will not change for the user.
+
+![User experience for users viewing limited permission Actor in console](./images/end_user_ux_limited_permissions.png)
+
+![User experience for users viewing full permission Actor in console](./images/end_user_ux_full_permissions.png)
+
+### Impact of permission level
+
+TODO: Section about current and future implications of keeping an actor on full
+
+TODO: Link to migration guide or inline it fully

sources/platform/actors/development/permissions/migration_guide.md

@@ -0,0 +1,40 @@
+---
+title: Migration guide
+description: How to migrate your Actor to work with limited permissions, including common questions and exact upgrade steps.
+sidebar_position: 9
+slug: /actors/development/permissions/migration-guide
+---
+
+**How to migrate your Actor to work with limited permissions, including common questions and exact upgrade steps.**
+
+---
+
+If you have existing Actors, or want to update your code for the new permission model, use this guide. The general prerequisite is to update the Actor to use the latest [Apify SDK](https://docs.apify.com/sdk).
+
+TODO: "callout about js and sdk minimal versions":
+- [js](https://github.com/apify/apify-sdk-js/releases/tag/apify%403.4.4)
+- [python](https://github.com/apify/apify-sdk-python/releases/tag/v3.0.0)
+
+Below you can read a guide that covers various, more advanced cases.
+
+## What changes compared to full permissions?
+
+- Actors now run with **limited permissions** by default (unless you explicitly request full permissions).
+- Limited permissions mean your Actor can only access its own default storages, storages supplied via input (granted by user), and certain account metadata.
+- Most platform APIs are still available, but operations affecting other users’ data are restricted.
+
+##  Common migration paths
+
+**Most Actors require no change**. If your Actor only uses its default dataset, key-value store, and request queue, it will keep working as before.
+
+If your Actor creates its own storages, runs other Actors, or needs access to user-provided storages:
+
+- Review your code for any Apify SDK calls that:
+  - Create storages (`Apify.openDataset()`, `Apify.openKeyValueStore()`, ...)
+  - Operate on storages not created by this run
+  - Run other Actors (metamorph, `Apify.call()`)
+- If you need access to a user-supplied storage, use the input schema `resourcePicker` input type and specify `resourcePermissions` your Actor needs (read more in the input schema docs).
+- If your Actor MUST run with full permissions (rare, discouraged), update the Actor settings in Console/API to request full permissions, and document why.
+
+If your Actor requests the /users/me endpoint to inspect data about the user:
+- If you need to check if the user is a paying user you can use the `` environment var or Actor