docs: security section by TC-MO · Pull Request #2888 · apify/apify-docs

TC-MO · 2026-08-18T12:17:58Z

Splits the single security page into an overview, vulnerability disclosure policy, shared responsibility model, and platform architecture. New additions based on drafts from @filakovsky; the security whitepaper stays an external PDF that the docs link rather than duplicate.

apify-service-account · 2026-08-18T12:18:50Z

🗑️ Preview for this PR was deleted.

filakovsky

I like it, thanks @TC-MO !

Split the standalone /security page into a multi-page section: an overview hub at /security and the full vulnerability disclosure policy at /security/vulnerability-disclosure. Add the security sidebar entry. Preserve the /security#vulnerability-disclosure-policy anchor on the hub so existing external links still resolve.

Add the shared responsibility model at /security/shared-responsibility and link it from the security hub. Keep the security whitepaper as an external PDF asset (linked, not duplicated in docs), matching the Actor whitepaper precedent and how peers publish security whitepapers.

…page Address review-docs findings: description lengths in range, drop article before Apify Store, spell out Apify Proxy in the table, active voice, and a missing-article grammar fix. Light prose tightening on the shared responsibility page (independently verified as lossless).

Updated wording for clarity on Actor runtime isolation.

Add a technical overview of how the platform is built: control and execution planes, the anatomy of an Actor run, workload isolation, storage, and availability. Scope it to mechanism and link out to the security pages for encryption, compliance, and data residency rather than duplicating them. Link it from the Get started overview.

…fixes Replace relative .md links and one hardcoded docs.apify.com URL with absolute slugs, so internal links follow a single style that also works for the SDK, CLI, and client docs served from other repos. Apply the first standards review of the architecture page and security hub: drop first-person 'our' from the hub, add missing image alt text, fix list parallelism, replace unmeasured claims and passive voice where the actor is known, and split sentences over the 30-word limit.

Satisfy the no-stacked-headings rule by introducing the customer and shared responsibility sections before their subheadings.

Run Actors and Build Actors are the two paths the overview points to. Architecture completes that arc for a general audience, while agent onboarding serves a narrower one and the overview already lists it under common next steps rather than as a path.

The page now sits with the security pages it cross-references. Two links that pointed back to the security overview target the shared responsibility model and the vulnerability disclosure policy instead.

Architecture moved to the security section, so the reorder it prompted no longer applies.

Give each fact one home. The design principles state intent, the cloud infrastructure section states the configuration, and the availability section states the consequence. Drop the residency reference the shared responsibility model does not cover, and name the subject of the orchestrator sentence.

… with a map Three sections on the overview restated the sidebar in prose. Replace them with a short list at the top, which also serves the markdown and llms.txt outputs where no sidebar exists. Drop the secrets guidance the shared responsibility model already covers, and split the opening sentence that promised both how the platform is built and how it is secured.

The dedupe pass treated an explanation and a headline claim as repetition. Put back the gloss on Availability Zone, restore the cross-account guarantee to the design principles where a reader skims for it, and give the reporting address on the overview so a researcher does not have to open another page to find it.

Drop the sentence that announced the page's audience, and name the actor in four sentences where Apify or the platform does the work.

szaganek

I'm not going to block it, so approved. I just hope you fix some of these things. There's a lot of filler here that makes it hard to read, a lot of "it's not X, it's Y", missing contractions, and generally repeated info that we could make more concise.

szaganek · 2026-09-10T05:51:22Z


 Because every Actor shares this input > run > output model, they compose. One Actor's output can feed another, results flow into [integrations](/integrations) like Make, Zapier, or n8n, and you can call any Actor from your code like a regular API.

+For how the platform itself is built - the control and execution planes, what happens during a run, and how workloads stay isolated - see [Platform architecture](/security/architecture).


Suggested change

For how the platform itself is built - the control and execution planes, what happens during a run, and how workloads stay isolated - see [Platform architecture](/security/architecture).

For how the platform is built, what happens during a run, and how workloads stay isolated, see [Platform architecture](/security/architecture).

Parenthetical like this one is unnecessary, keep it simple.

szaganek · 2026-09-10T05:52:10Z

+description: How the Apify platform is built - control and execution planes, what happens during an Actor run, how workloads stay isolated, and how storage works.
+---
+
+This page describes how the Apify platform is built: how it is structured, what happens when an Actor runs, how workloads stay isolated, and how data is stored.


Suggested change

This page describes how the Apify platform is built: how it is structured, what happens when an Actor runs, how workloads stay isolated, and how data is stored.

Learn how the Apify platform is built: how it is structured, what happens when an Actor runs, how workloads stay isolated, and how data is stored.

Why describe the guide, when we can be more task-oriented?

szaganek · 2026-09-10T05:53:09Z

+
+This page describes how the Apify platform is built: how it is structured, what happens when an Actor runs, how workloads stay isolated, and how data is stored.
+
+Security controls and the division of responsibilities are covered separately in the [shared responsibility model](/security/shared-responsibility) and the [Apify Security Whitepaper](https://apify.com/security-whitepaper.pdf).


Suggested change

Security controls and the division of responsibilities are covered separately in the [shared responsibility model](/security/shared-responsibility) and the [Apify Security Whitepaper](https://apify.com/security-whitepaper.pdf).

For security controls and the division of responsibilities, see [shared responsibility model](/security/shared-responsibility) and the [Apify Security Whitepaper](https://apify.com/security-whitepaper.pdf).

It's a good practice to avoid passive voice.

szaganek · 2026-09-10T05:54:32Z

+
+## Design principles
+
+A few principles shape most of the decisions described below:


This sentence says a lot of nothing. Whose decisions? Why directional language? Can we make it a proper intro?

szaganek · 2026-09-10T05:56:25Z

+- Control plane. Apify Console, the Apify API, and the supporting services. This is where you and your integrations manage Actors, tasks, schedules, storage, and billing.
+- Execution plane. Actor runs execute here, together with the storage that holds their inputs and results.
+
+The two planes run as separate systems. The execution plane still depends on the API to authenticate, read inputs, and store results. Every action a run takes against platform data therefore passes through the API's authorization checks rather than reaching storage directly.


still, therefore, rather than -- that's all unnecessary AI filler. Can you try to rewrite in plain English?

szaganek · 2026-09-10T06:02:54Z

+
+The platform protects your data with redundancy, backups, and safeguards against accidental deletion:
+
+- Redundancy. The data your Actors collect (datasets, key-value stores, request queues) lives in Amazon S3 and DynamoDB, replicated across multiple Availability Zones - S3 is designed for 99.999999999% (11 nines) durability. The primary database runs as a replicated cluster across zones too, so the loss of a node or zone loses no data.


S3 is designed for 99.999999999% (11 nines) durability -- is this necessary?

szaganek · 2026-09-10T06:04:28Z

+The platform protects your data with redundancy, backups, and safeguards against accidental deletion:
+
+- Redundancy. The data your Actors collect (datasets, key-value stores, request queues) lives in Amazon S3 and DynamoDB, replicated across multiple Availability Zones - S3 is designed for 99.999999999% (11 nines) durability. The primary database runs as a replicated cluster across zones too, so the loss of a node or zone loses no data.
+- Backups. The primary database is backed up automatically by the managed database service it runs on. These backups let the platform recover from a serious failure; they are not an archive of individual accounts.


Suggested change

- Backups. The primary database is backed up automatically by the managed database service it runs on. These backups let the platform recover from a serious failure; they are not an archive of individual accounts.

- Backups. The primary database is backed up automatically by the managed database service it runs on. These backups let the platform recover from a serious failure, they aren't an archive of individual accounts.

szaganek · 2026-09-10T06:05:49Z

+
+## Availability and resilience
+
+The loss of a single Availability Zone - a physically separate data center within the region - does not take the platform down. Availability rests on several mechanisms:


Why a parenthetical again? Define the term first, then talk about the consequences.

szaganek · 2026-09-10T06:09:52Z

+    <img src={require("../images/security/soc2-logo.png").default} alt="SOC 2 Type II compliance badge" width="150" title="Apify SOC 2 Type II compliance" />
+</a>
+
+To learn more, read the [SOC 2 compliance announcement](https://blog.apify.com/apify-soc2/) and visit the [Trust Center](https://trust.apify.com) for additional information or to request the SOC 2 Type II report.


There's "to learn more" and "for additional information" in one sentence. It could be more concise.

szaganek · 2026-09-10T06:10:19Z

+
+## Security whitepaper
+
+For a comprehensive description of how the Apify platform is built and operated to protect your data, read the [Apify Security Whitepaper](https://apify.com/security-whitepaper.pdf).


Suggested change

For a comprehensive description of how the Apify platform is built and operated to protect your data, read the [Apify Security Whitepaper](https://apify.com/security-whitepaper.pdf).

For how the Apify platform is built and operated to protect your data, read the [Apify Security Whitepaper](https://apify.com/security-whitepaper.pdf).

Address the review on #2888: replace the empty opener to the design principles, cut the parentheticals and the vague quantifiers, define Availability Zone before stating what losing one means, and drop the connectives that padded the two-planes paragraph.

…ty pages The style guide asks for contractions and for consistency within a page, so contract the declarative statements throughout rather than only the two lines raised in review. Imperative warnings keep the full form.

Replace the S3 durability figure with a plain statement of high durability, since we can't commit to the same numbers as our provider, and cut the accidental-deletion sentence that repeated the safeguards described before it.

The run walkthrough and the Apify Proxy section both explained that target sites see proxy addresses, in slightly different words. Leave the explanation with the proxy section and let the walkthrough name the step.

TC-MO requested a review from filakovsky August 18, 2026 12:17

TC-MO self-assigned this Aug 18, 2026

TC-MO added documentation Improvements or additions to documentation. t-docs Issues owned by technical writing team. labels Aug 18, 2026

TC-MO changed the title ~~Docs/security section~~ docs: security section Aug 18, 2026

filakovsky approved these changes Aug 24, 2026

View reviewed changes

TC-MO and others added 7 commits August 28, 2026 10:32

docs(security): clarify Actor runtime isolation description

4e67990

Updated wording for clarity on Actor runtime isolation.

docs(security): add lead-in text under shared responsibility headings

fee4ff8

Satisfy the no-stacked-headings rule by introducing the customer and shared responsibility sections before their subheadings.

TC-MO force-pushed the docs/security-section branch from d81d5fd to fee4ff8 Compare August 28, 2026 08:36

TC-MO and others added 8 commits August 28, 2026 11:03

docs(security): add backup section

f70b881

docs(security): move architecture page to the security section

90e5389

The page now sits with the security pages it cross-references. Two links that pointed back to the security overview target the shared responsibility model and the vulnerability disclosure policy instead.

docs(get-started): restore agent onboarding position

58a5c41

Architecture moved to the security section, so the reorder it prompted no longer applies.

docs(security): tighten the voice on the architecture page

d631553

Drop the sentence that announced the page's audience, and name the actor in four sentences where Apify or the platform does the work.

TC-MO marked this pull request as ready for review September 3, 2026 09:52

TC-MO requested a review from szaganek September 3, 2026 09:53

szaganek approved these changes Sep 10, 2026

View reviewed changes

TC-MO added 4 commits September 10, 2026 12:16

docs(security): state the proxy IP behavior once

3bc4118

The run walkthrough and the Apify Proxy section both explained that target sites see proxy addresses, in slightly different words. Leave the explanation with the proxy section and let the walkthrough name the step.

TC-MO merged commit e8a06ab into master Sep 10, 2026
14 checks passed

TC-MO deleted the docs/security-section branch September 10, 2026 11:27


		Because every Actor shares this input > run > output model, they compose. One Actor's output can feed another, results flow into [integrations](/integrations) like Make, Zapier, or n8n, and you can call any Actor from your code like a regular API.

		For how the platform itself is built - the control and execution planes, what happens during a run, and how workloads stay isolated - see [Platform architecture](/security/architecture).

	For how the platform itself is built - the control and execution planes, what happens during a run, and how workloads stay isolated - see [Platform architecture](/security/architecture).
	For how the platform is built, what happens during a run, and how workloads stay isolated, see [Platform architecture](/security/architecture).

	This page describes how the Apify platform is built: how it is structured, what happens when an Actor runs, how workloads stay isolated, and how data is stored.
	Learn how the Apify platform is built: how it is structured, what happens when an Actor runs, how workloads stay isolated, and how data is stored.


		This page describes how the Apify platform is built: how it is structured, what happens when an Actor runs, how workloads stay isolated, and how data is stored.

		Security controls and the division of responsibilities are covered separately in the [shared responsibility model](/security/shared-responsibility) and the [Apify Security Whitepaper](https://apify.com/security-whitepaper.pdf).

	Security controls and the division of responsibilities are covered separately in the [shared responsibility model](/security/shared-responsibility) and the [Apify Security Whitepaper](https://apify.com/security-whitepaper.pdf).
	For security controls and the division of responsibilities, see [shared responsibility model](/security/shared-responsibility) and the [Apify Security Whitepaper](https://apify.com/security-whitepaper.pdf).


		## Design principles

		A few principles shape most of the decisions described below:


		The platform protects your data with redundancy, backups, and safeguards against accidental deletion:

		- Redundancy. The data your Actors collect (datasets, key-value stores, request queues) lives in Amazon S3 and DynamoDB, replicated across multiple Availability Zones - S3 is designed for 99.999999999% (11 nines) durability. The primary database runs as a replicated cluster across zones too, so the loss of a node or zone loses no data.

	- Backups. The primary database is backed up automatically by the managed database service it runs on. These backups let the platform recover from a serious failure; they are not an archive of individual accounts.
	- Backups. The primary database is backed up automatically by the managed database service it runs on. These backups let the platform recover from a serious failure, they aren't an archive of individual accounts.


		## Availability and resilience

		The loss of a single Availability Zone - a physically separate data center within the region - does not take the platform down. Availability rests on several mechanisms:


		## Security whitepaper

		For a comprehensive description of how the Apify platform is built and operated to protect your data, read the [Apify Security Whitepaper](https://apify.com/security-whitepaper.pdf).

	For a comprehensive description of how the Apify platform is built and operated to protect your data, read the [Apify Security Whitepaper](https://apify.com/security-whitepaper.pdf).
	For how the Apify platform is built and operated to protect your data, read the [Apify Security Whitepaper](https://apify.com/security-whitepaper.pdf).

Uh oh!

Conversation

TC-MO commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

apify-service-account commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

filakovsky left a comment

Choose a reason for hiding this comment

Uh oh!

szaganek left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

TC-MO commented Aug 18, 2026 •

edited

Loading

apify-service-account commented Aug 18, 2026 •

edited

Loading