diff --git a/sources/platform/collaboration/general-resource-access.md b/sources/platform/collaboration/general-resource-access.md new file mode 100644 index 0000000000..f3b771fe65 --- /dev/null +++ b/sources/platform/collaboration/general-resource-access.md @@ -0,0 +1,174 @@ +--- +title: General resource access +description: Control how Apify resources are shared. Set default access (Anyone with ID can read or Restricted), and learn about link sharing, exceptions, and pre-signed URLs. +sidebar_position: 1 +category: platform +slug: /collaboration/general-resource-access +--- + +Some resources, like storages, Actor runs or Actor builds, can be shared simply by sending their unique resource ID or Console link and the recipient can then view the data in Console or fetch it via API without needing an API token. This is very useful for ad-hoc collaboration, integrating third party tools that connect to data in your Apify account or quick prototypes. + +Thanks to the hard-to-guess, unique IDs, it’s also secure enough for most use cases. However, it doesn't offer features like access revocation and in some cases, you may want to have more direct control over data access and require users to have explicit permissions to your resources. + +**General resource access** is an account setting that defines the default access policy at the account level. You can find General resource access in Apify Console under **Settings → Security & Privacy**. The two following options are supported: + +- **Anyone with ID can read (default)**: Selected resources can be accessed using just their unique resource ID. This means if you share the resource ID with someone, they would be able to view it without providing an API token or viewing the resource by visiting the Console URL. +- **Restricted**: With this setting, only signed-in users with an explicit access to the resources can access them. To access restricted resources via API, a valid token needs to be provided. + +This setting affects the following resources: + +- Actor runs +- Actor builds +- Storages: + - Datasets + - Key-value stores + - Request queues + +Access to resources that require explicit access — such as Actors, tasks or schedules are not affected by this setting. + +![Setup account-level general resources access setting](./images/general-resouce-access//account-setting.png) + +## How Restricted Access works + +If your **General resource access** is set to **Anyone with ID can read**, you can just send this link to anybody, and they will be able to download the data even if they don’t have an Apify account. However, once you change the setting to **Restricted**, this API call will require a valid token with access in order to work. In other words, you’ll have to explicitly share the dataset and you can only do that with people who have an Apify account. + +:::tip Access Setting Changes May Be Delayed +When you change the access for a resource it may take a minute for the change to take effect. +::: + +### What is the best setting for me + +Sharing by link is quick, convenient, and secure enough for most use cases -- thanks to the use of hard-to-guess unique IDs. + +That said, link-based sharing doesn’t support access revocation, audit trails, or fine-grained permission controls. If you need tighter control over who can access your data or require elevated security because of the domain you're working in we recommend enabling **Restricted** access. + +The default setting strikes a good balance for casual or internal use, but **Restricted** access is a better fit for teams with stricter security policies, integrations using scoped API tokens, or audit requirements. + +You can switch to **Restricted** access at any time. If it causes issues in your workflow, you can revert to the default setting just as easily. + +:::note Support in public Actors +Because this is a new setting, some existing public Actors and integrations might not support it yet. Their authors need to update them to provide a valid token on all API calls. +::: + + +### Exceptions + +Even if your access is set to **Restricted** there are a few built-in exceptions that make collaboration and platform features work seamlessly. These are explained in the sections below. + + +#### Builds of public Actors + +Builds of public Actors are always accessible to anyone who can view the Actor — regardless of the Actor owner’s account **General resource access** setting. + +This ensures that public Actors in the Apify Store continue to work as expected. For example, if you open a public Actor in Console, you’ll also be able to view its build details, download logs, or inspect the source package — without needing extra permissions or a token. + +This exception exists to maintain usability and avoid breaking workflows that rely on public Actors. It only applies to builds of Actors that are marked as **public**. For private Actors, build access still follows the general resource access setting of the owner’s account. + +#### Automatically share owner runs of shared Actors & Tasks with collaborators + +When you share an Actor with a collaborator, you can choose to share read-only access to your (the owner’s) runs of that Actor. This makes it easier for them to help with debugging, monitoring, or reviewing outputs. + +- This access includes logs, input, and default storages (dataset, key-value store, request queue) +- Access is one-way: you won’t see the collaborator’s runs unless they share them +- Collaborators can’t see each other’s runs +- This works even if your account uses **restricted general resource access** — permissions are applied automatically. + +#### Automatically sharing runs with public Actor creators + +If you’re using a public Actor from the Apify Store, you can choose to automatically share your runs of that Actor with its creator. This helps developers monitor usage and troubleshoot issues more effectively. + +- This setting is opt-in and can be enabled under **Account Settings → Privacy** +- When enabled, your runs of public Actors are automatically visible to the Actor’s creator +- Shared runs include logs, input, and output storages (dataset, key-value store, request queue) + +This sharing works even if your account has **General resource access** set to **Restricted** — the platform applies specific permission checks to ensure the Actor creator can access only the relevant runs. + +You can disable this behavior at any time by turning off the setting in your account. + +#### Automatically sharing runs via Actor Issues + +When you report an issue on an Actor and include a **run URL**, that run is automatically shared with the Actor developer — **even if your account uses restricted general resource access**. + +This automatic sharing ensures the developer can view all the context they need to troubleshoot the issue effectively. That includes: + +- Full access to the run itself (logs, input, status) +- Automatic access to the run’s default storages: + - Dataset + - Key-value store + - Request queue + +The access is granted through explicit, behind-the-scenes permissions (not anonymous or public access), and is limited to just that run and its related storages. No other resources in your account are affected. + +This means you don’t need to manually adjust permissions or share multiple links when reporting an Actor issue — **just including the run URL in your issue is enough** + +![Sharing a run link in create Actor issue dialog makes it accessible to the developer automatically](./images/general-resouce-access/creating-actor-issue.png) + +## Per-resource access control + +The account level access control can be changed on individual resources. This can be done by setting the general access level to other than Restricted in the share dialog for a given resource. This way the resource level setting takes precedence over the account setting. + +![Setup resource level access control](./images/general-resouce-access/share-resource-dialog.png) + +:::tip Using Apify API +You can also set the general access on a resource programmatically using the Apify API or Apify client. Read more in the API reference and client documentation. + +```js +const datasetClient = apifyClient.dataset(datasetId); +await datasetClient.update({ + generalAccess: STORAGE_GENERAL_ACCESS.ANYONE_WITH_ID_CAN_READ +}); +``` + +::: + +### Sharing restricted resources with pre-signed URLs {#pre-signed-urls} + +Even when a resource is restricted, you might still want to share it with someone outside your team — for example, to send a PDF report to a client, or include a screenshot in an automated email or Slack message. In these cases, **storage resources** (like key-value stores, datasets, and request queues) support generating **pre-signed URLs**. These are secure, time-limited links that let others access individual files without needing an Apify account or authentication. + +Pre-signed URLs: + +- Work even when General resource access is restricted +- Expire automatically after 14 days (by default) +- Are scoped to a single resource (prevents access to other records) +- Are ideal for sharing screenshots, reports, or any other one-off files + +To generate a pre-signed link, you can use the **Export** button in Console, or call the appropriate API client method. + +![Generating shareable link for a restricted storage resource](./images/general-resouce-access/copy-shareable-link.png) + +:::info Console links for resources + +Resource objects returned by the API and clients (like `apify-client-js`) include a `consoleUrl` property. This provides a stable link to the resource's page in the Apify Console. Unlike a direct API link, Console link will prompt unauthenticated users to sign in, ensuring they have required permissions to view the resource. + +This is ideal for use-cases like email notifications or other automated workflows. + +::: + +### Sharing storages by name + +A convenient feature of storages is that you can name them. If you choose to do so there is an extra access level setting that applies to storages only, which is **Anyone with name or ID can read**. In that case anyone that knows the storage name is able to read it via API or view it using the storages Console URL. + +:::tip Exposing public named datasets + +This is very useful if you wish to expose a storage publicly with an easy to remember URL. + +::: + +## Implications for public Actor developers + +If you own a public Actor in the Apify Store, you need to make sure that your Actor will work even for users who have restricted access to their resources. Over time, you might see a growing number of users with **General resource access** set to **Restricted**. + +:::tip Testing public access behavior + +To test your public Actor, run it using an account with **General resource access** set to restricted. You can use your developer account, or create a temporary testing Apify account. + +::: + +In practice, this means that all API calls originating from the Actor need to have a valid API token. If you are using Apify SDK, this should be the default behavior. + + +:::caution Actor Runs Inherit User Permissions + +Keep in mind that when users run your public Actor, the Actor makes API calls under the user account, not your developer account. This means that it follows the **General resource access** configuration of the user account. The configuration of your developer account has no effect on the Actor users. + +::: diff --git a/sources/platform/collaboration/images/general-resouce-access/account-setting.png b/sources/platform/collaboration/images/general-resouce-access/account-setting.png new file mode 100644 index 0000000000..9f5f0d738f Binary files /dev/null and b/sources/platform/collaboration/images/general-resouce-access/account-setting.png differ diff --git a/sources/platform/collaboration/images/general-resouce-access/copy-shareable-link.png b/sources/platform/collaboration/images/general-resouce-access/copy-shareable-link.png new file mode 100644 index 0000000000..7b84c077ad Binary files /dev/null and b/sources/platform/collaboration/images/general-resouce-access/copy-shareable-link.png differ diff --git a/sources/platform/collaboration/images/general-resouce-access/creating-actor-issue.png b/sources/platform/collaboration/images/general-resouce-access/creating-actor-issue.png new file mode 100644 index 0000000000..dba5b55988 Binary files /dev/null and b/sources/platform/collaboration/images/general-resouce-access/creating-actor-issue.png differ diff --git a/sources/platform/collaboration/images/general-resouce-access/share-resource-dialog.png b/sources/platform/collaboration/images/general-resouce-access/share-resource-dialog.png new file mode 100644 index 0000000000..c883b0be96 Binary files /dev/null and b/sources/platform/collaboration/images/general-resouce-access/share-resource-dialog.png differ diff --git a/sources/platform/collaboration/index.md b/sources/platform/collaboration/index.md index 49d134b23e..18aad02362 100644 --- a/sources/platform/collaboration/index.md +++ b/sources/platform/collaboration/index.md @@ -9,14 +9,28 @@ slug: /collaboration **Learn how to collaborate with other users and manage permissions for organizations or private resources such as Actors, Actor runs, and storages.** --- +Apify was built from the ground up as a collaborative platform. Whether you’re publishing your Actor in Apify Store or sharing a dataset with a teammate, collaboration is deeply integrated into how Apify works. You can share your resources (like Actors, runs, or storages) with others, manage permissions, or invite collaborators to your organization. By default, each system resource you create is only available to you, the owner. However, you can grant access to other users, making it easy to collaborate effectively and securely. -By default, each system resource (Actor, key-value store, run, ...) you create is only available to you, the owner. You can grant access to your resources in three ways: +While most resources can be shared by assigning permissions (see [Access Rights](./access_rights.md)), some resources can also be shared simply by using their unique links or IDs. There are two types of resources in terms of sharing: + +- _Resources that require explicit access by default:_ + - [Actors](../actors/running/index.md), [tasks](../actors/running/tasks.md) + - Can be shared only by inviting collaborators using [Access Rights](./access_rights.md)) or using [Organization Accounts](./organization_account/index.md) +- _Resources supporting both explicit access and link sharing:_ + - Actor runs, Actor builds and storage resources (datasets, key-value stores, request queues) + - Can be shared by inviting collaborators or simply by sharing a unique direct link + +You can control access to your resources in four ways: + + + + diff --git a/sources/platform/storage/dataset.md b/sources/platform/storage/dataset.md index f966ba800b..b56d6008d9 100644 --- a/sources/platform/storage/dataset.md +++ b/sources/platform/storage/dataset.md @@ -382,6 +382,10 @@ By default, the whole result is wrapped in an `` element, while each pag You can grant [access rights](../collaboration/index.md) to your dataset through the **Share** button under the **Actions** menu. For more details, check the [full list of permissions](../collaboration/list_of_permissions.md). +You can also share datasets by link using their ID or name, depending on your account or resource-level general access setting. Learn how link-based access works in [General resource access](/platform/collaboration/general-resource-access). + +For one-off sharing of specific records when access is restricted, you can generate time-limited pre-signed URLs. See [Sharing restricted resources with pre-signed URLs](/platform/collaboration/general-resource-access#pre-signed-urls). + ### Sharing datasets between runs You can access a dataset from any [Actor](../actors/index.mdx) or [task](../actors/running/tasks.md) run as long as you know its _name_ or _ID_. diff --git a/sources/platform/storage/key_value_store.md b/sources/platform/storage/key_value_store.md index ffe40d484c..9d86b0aeb7 100644 --- a/sources/platform/storage/key_value_store.md +++ b/sources/platform/storage/key_value_store.md @@ -256,6 +256,10 @@ _Using the [JavaScript SDK](/sdk/js/reference/class/KeyValueStore#setValue) or o You can grant [access rights](../collaboration/index.md) to your key-value store through the **Share** button under the **Actions** menu. For more details check the [full list of permissions](../collaboration/list_of_permissions.md). +You can also share key-value stores by link using their ID or name, depending on your account or resource-level general access setting. Learn how link-based access works in [General resource access](/platform/collaboration/general-resource-access). + +For one-off sharing of specific records when access is restricted, you can generate time-limited pre-signed URLs. See [Sharing restricted resources with pre-signed URLs](/platform/collaboration/general-resource-access#pre-signed-urls). + ### Sharing key-value stores between runs You can access a key-value store from any [Actor](../actors/index.mdx) or [task](../actors/running/tasks.md) run as long as you know its _name_ or _ID_. diff --git a/sources/platform/storage/request_queue.md b/sources/platform/storage/request_queue.md index 64db8ec128..29e3d71cd3 100644 --- a/sources/platform/storage/request_queue.md +++ b/sources/platform/storage/request_queue.md @@ -558,6 +558,10 @@ A detailed tutorial on how to process one request queue with multiple Actor runs You can grant [access rights](../collaboration/index.md) to your request queue through the **Share** button under the **Actions** menu. For more details check the [full list of permissions](../collaboration/list_of_permissions.md). +You can also share request queues by link using their ID or name, depending on your account or resource-level general access setting. Learn how link-based access works in [General resource access](/platform/collaboration/general-resource-access). + +For one-off sharing of specific records when access is restricted, you can generate time-limited pre-signed URLs. See [Sharing restricted resources with pre-signed URLs](/platform/collaboration/general-resource-access#pre-signed-urls). + ### Sharing request queues between runs You can access a request queue from any [Actor](../actors/index.mdx) or [task](../actors/running/tasks.md) run as long as you know its _name_ or _ID_. diff --git a/sources/platform/storage/usage.md b/sources/platform/storage/usage.md index ee1a57c25d..ac55550620 100644 --- a/sources/platform/storage/usage.md +++ b/sources/platform/storage/usage.md @@ -160,7 +160,17 @@ For example, storage names `janedoe~my-storage-1` and `janedoe~web-scrape-result ## Sharing -You can grant [access rights](../collaboration/index.md) to others Apify users to view or modify your storages. Check the [full list of permissions](../collaboration/list_of_permissions.md). +You can grant [access rights](../collaboration/index.md) to other Apify users to view or modify your storages. Check the [full list of permissions](../collaboration/list_of_permissions.md). + +You can also share storages by link using their ID or name, depending on your account or resource-level general access setting. Learn how link-based access works in [General resource access](/platform/collaboration/general-resource-access). + +For one-off sharing when access is restricted, generate time-limited pre-signed URLs. See [Sharing restricted resources with pre-signed URLs](/platform/collaboration/general-resource-access#pre-signed-urls). + +:::tip Accessing restricted storage resources via API + +If your storage resource is set to _restricted_, all API calls must include a valid authentication token in the `Authorization` header. If you're using **apify-client** the header is passed in automatically. + +::: ### Sharing storages between runs @@ -173,6 +183,13 @@ Storage can be accessed from any [Actor](../actors/index.mdx) or [task](../actor > When multiple runs try to write data to a storage simultaneously, the order of data writing cannot be controlled. Data is written as each request is processed.
> Similar principle applies in key-value stores and request queues, when a delete request for a record precedes a read request for the same record, the read request will fail. +:::info Accessing restricted storage resources between runs + +If a storage resource access is set to **Restricted**,the run from which it's accessed must have explicit access to it. +Learn how restricted access works in [General resource access](/platform/collaboration/general-resource-access). + +::: + ## Deleting storages Named storages are only removed upon your request.
Access rights Enables you to grant access to another user for a certain resource you own. This way, you can share results with your client, or two engineers can collaborate on developing one Actor.
Share resources by linkCertain resources (runs, builds and storages) can by shared just by their link. Anyone with their ID is able to access them. This is configurable via General resource access
Organization account Apify's organization account allows multiple engineers to collaborate on team projects with role-specific access permissions.