|
| 1 | +--- |
| 2 | +title: Migration guide |
| 3 | +description: How to migrate your Actor to limited permissions. Common migration paths, code examples, and common issues. |
| 4 | +sidebar_position: 9 |
| 5 | +slug: /actors/development/permissions/migration-guide |
| 6 | +--- |
| 7 | + |
| 8 | +**Migrate your Actor to limited permissions, review common migration paths, code examples, and solutions to common issues.** |
| 9 | + |
| 10 | +--- |
| 11 | + |
| 12 | +This guide explains how to migrate your existing Actors to use [limited permissions](index.md#how-actor-permissions-work). Before you start, make sure your Actor uses the latest [Apify SDK](https://docs.apify.com/sdk). |
| 13 | + |
| 14 | +Recommended minimum SDK versions: |
| 15 | + |
| 16 | +- JavaScript SDK: [[email protected]](https://github.com/apify/apify-sdk-js/releases/tag/apify%403.4.4) |
| 17 | +- Python SDK: [v3.0.0](https://github.com/apify/apify-sdk-python/releases/tag/v3.0.0) |
| 18 | + |
| 19 | +Before you start it's helpful to understand [what access restrictions limited permissions impose](index.md#how-actor-permissions-work). |
| 20 | + |
| 21 | +## Test your Actor with limited permissions before migrating |
| 22 | + |
| 23 | +You can override the permission level for a single run using run options under the **Actor Source** tab in Console: |
| 24 | + |
| 25 | + |
| 26 | + |
| 27 | +You can do the same using the Apify Client as well: |
| 28 | + |
| 29 | +```ts |
| 30 | +await apifyClient.actor(actorId).call(input, { |
| 31 | + forcePermissionLevel: ACTOR_PERMISSION_LEVEL.LIMITED_PERMISSIONS, |
| 32 | +}); |
| 33 | +``` |
| 34 | + |
| 35 | +Or just using the API: |
| 36 | + |
| 37 | +```tsx |
| 38 | + POST https://api.apify.com/v2/acts/<actor_id>/runs?**forcePermissionLevel=LIMITED_PERMISSIONS** |
| 39 | +``` |
| 40 | + |
| 41 | + |
| 42 | +## Common migration paths |
| 43 | + |
| 44 | +Most public Actors can migrate to limited permissions with minor adjustments, if any. The general prerequisite is to **update the Actor to use the latest [Apify SDK](https://docs.apify.com/sdk)**. To assess what needs to change in your Actor, review these areas: |
| 45 | + |
| 46 | +- How your Actor uses storages (e.g. named storages and storages provided via input) |
| 47 | +- Whether it requests correct resource access for user-provided storages |
| 48 | +- Whether it needs to access information about the user (specifically if the user is paying or access their proxy configuration) |
| 49 | + |
| 50 | +Once you have updated and [tested](#test-your-actor-with-limited-permissions-before-migrating) your Actor, you can change the permissions in the Actor settings. The setting takes immediate effect. |
| 51 | + |
| 52 | +Below you can review common migration paths for advanced cases in greater detail. |
| 53 | + |
| 54 | +### The Actor only pushes data to default storages |
| 55 | + |
| 56 | +This is the most common and simplest use case. If your Actor only reads its input and writes results to its default dataset, key-value store, or request queue, _no changes are needed_. Limited permissions fully support this behavior out of the box. |
| 57 | + |
| 58 | +### The Actor calls other Actors |
| 59 | + |
| 60 | +An Actor with limited permissions can only call other Actors that also have limited permissions. If your Actor calls another one, you will need to ensure the target Actor has been migrated first. |
| 61 | + |
| 62 | +### The Actor accesses storages provided by the user |
| 63 | + |
| 64 | +If your Actor reads from or writes to a storage that the user provides via an input field, you must explicitly declare what access you need in the Actor's input schema. |
| 65 | + |
| 66 | +1. Populate `resourceType` property on the field to enable the native resource picker. |
| 67 | +1. Populate `resourcePermissions` with permissions you need for the resource. |
| 68 | + |
| 69 | +For example, your Actor allows the user to provide a custom dataset for the Actor results. Your `input_schema.json` might contain something like this: |
| 70 | + |
| 71 | +```json |
| 72 | +{ |
| 73 | + "title": "Output", |
| 74 | + "type": "string", |
| 75 | + "description": "Select a dataset for the Actor results", |
| 76 | +} |
| 77 | +``` |
| 78 | + |
| 79 | +To support limited permissions, change it to this: |
| 80 | + |
| 81 | +```json |
| 82 | +{ |
| 83 | + "title": "Output", |
| 84 | + "type": "string", |
| 85 | + "description": "Select a dataset for the Actor results", |
| 86 | + "resourceType": "dataset", |
| 87 | + "resourcePermissions": ["READ", "WRITE"], |
| 88 | + "editor": "textfield", // If you want to preserve the plain "string" input UI, instead of rich resource picker. |
| 89 | +} |
| 90 | +``` |
| 91 | + |
| 92 | +Now when the platform runs your Actor, it’ll automatically add the user-provided storage to the Actor’s scope so that it can access it. |
| 93 | + |
| 94 | +:::info Backward compatibility |
| 95 | + |
| 96 | +Users can provide the resource both via its name and its ID. If you have users with inputs that specify the resource via its name, this change to the input schema will not break it. |
| 97 | + |
| 98 | +::: |
| 99 | + |
| 100 | +### The Actor accesses named storages |
| 101 | + |
| 102 | +Actors sometimes use named storages for caching or persisting state across runs. With limited permissions, an Actor can create a named storage on its first run and will automatically retain access to it in all subsequent runs by the same user. |
| 103 | + |
| 104 | +If your Actor previously relied on accessing a pre-existing named storage, you will need to rename it in your code. This will cause the Actor to recreate the storage under the new system on its next run. |
| 105 | + |
| 106 | +To achieve a smooth migration without disrupting your Actor’s users, you will need to make sure that your Actor can handle the transition. The suggested approach is the following: |
| 107 | + |
| 108 | +1. Adjust the code of the Actor so that it can run with both limited and full permissions. |
| 109 | +1. Change the Actor setting to limited permissions. |
| 110 | +1. Clean up the migration code. |
| 111 | + |
| 112 | +```ts |
| 113 | +const OLD_CACHE_STORE_NAME = 'my-actor-cache'; |
| 114 | +const NEW_CACHE_STORE_NAME = 'my-actor-cache-updated'; |
| 115 | + |
| 116 | +let store; |
| 117 | + |
| 118 | +if (process.env.ACTOR_PERMISSION_LEVEL === 'LIMITED_PERMISSIONS') { |
| 119 | + // If the Actor is running with limited permissions and we need to create |
| 120 | + // a new store. The platform will remember that the store was created by this Actor |
| 121 | + // and will allow access in all follow-up runs. |
| 122 | + store = await Actor.openKeyValueStore(NEW_CACHE_STORE_NAME); |
| 123 | +} else { |
| 124 | + // If the Actor is still running with full permissions and we should use |
| 125 | + // the existing store. |
| 126 | + store = await Actor.openKeyValueStore(OLD_CACHE_STORE_NAME); |
| 127 | +} |
| 128 | +``` |
| 129 | + |
| 130 | +:::info Re-create cache only under limited permissions. |
| 131 | + |
| 132 | +Create the new storage _only once the Actor runs with limited permissions_. Only that way the access is retained in follow-up runs. |
| 133 | + |
| 134 | +::: |
| 135 | + |
| 136 | +If the contents of the named storage are critical for your Actor to keep functioning for users and it is impossible, costly or highly impractical to migrate, contact support or reach out to us [on the community forum](https://discord.gg/eN73Xdhtqc). We can discuss the available options. |
| 137 | + |
| 138 | +### The Actor needs to know whether the user is paying |
| 139 | + |
| 140 | +Some Actors have different logic for free and paying users. Previously you could retrieve this information by calling the `/users/me` API endpoint. However, Actors running under limited permissions don't have access to that endpoint. To get this information, your Actor should read the `APIFY_USER_IS_PAYING` environment variable, or use the SDK to obtain the value: |
| 141 | + |
| 142 | +```ts |
| 143 | +const { userIsPaying } = Actor.getEnv(); |
| 144 | +``` |
| 145 | + |
| 146 | +### The Actor uses Proxy |
| 147 | + |
| 148 | +Similarly, if your Actor uses [Proxy](../../../proxy/index.md) and needs to retrieve the user's proxy password, it should get it from the `APIFY_PROXY_PASSWORD` environment variable instead of calling the `/users/me` endpoint or, preferably, rely on the SDK to handle proxy configuration automatically. |
0 commit comments