Permission docs

docs/en/reference/dataobject.md

@@ -192,6 +192,41 @@ To include relations in your summaries, you can use a dot-notation.
 	   );
 	}
 
+## Permissions
+
+Models can be modified in a variety of controllers and user interfaces,
+all of which can implement their own security checks. But often it makes
+sense to centralize those checks on the model, regardless of the used controller.
+
+The API provides four methods for this purpose: 
+`canEdit()`, `canCreate()`, `canView()` and `canDelete()`.
+Since they're PHP methods, they can contain arbitrary logic
+matching your own requirements. They can optionally receive a `$member` argument,
+and default to the currently logged in member (through `Member::currentUser()`).
+
+Example: Check for CMS access permissions
+
+	class MyDataObject extends DataObject {
+	  // ...
+		public function canView($member = null) {
+			return Permission::check('CMS_ACCESS_CMSMain', 'any', $member);
+		}
+		public function canEdit($member = null) {
+			return Permission::check('CMS_ACCESS_CMSMain', 'any', $member);
+		}
+		public function canDelete($member = null) {
+			return Permission::check('CMS_ACCESS_CMSMain', 'any', $member);
+		}
+		public function canCreate($member = null) {
+			return Permission::check('CMS_ACCESS_CMSMain', 'any', $member);
+		}
+	}
+
+**Important**: These checks are not enforced on low-level ORM operations
+such as `write()` or `delete()`, but rather rely on being checked in the invoking code.
+The CMS default sections as well as custom interfaces like
+`[ModelAdmin](/reference/modeladmin)` or `[GridField](/reference/gridfield)`
+already enforce these permissions.
 
 ## API Documentation
 

docs/en/reference/modeladmin.md

@@ -44,6 +44,34 @@ We'll name it `MyAdmin`, but the class name can be anything you want.
 This will automatically add a new menu entry to the CMS, and you're ready to go!
 Try opening http://localhost/admin/products/?flush=all.
 
+## Permissions
+
+Each new `ModelAdmin` subclass creates its own [permission code](/reference/permission),
+for the example above this would be `CMS_ACCESS_MyAdmin`. Users with access to the CMS
+need to have this permission assigned through `admin/security/` in order to gain
+access to the controller (unless they're admins).
+
+The `DataObject` API has more granular permission control, which is enforced in ModelAdmin by default. 
+Available checks are `canEdit()`, `canCreate()`, `canView()` and `canDelete()`.
+Models check for administrator permissions by default. For most cases,
+less restrictive checks make sense, e.g. checking for general CMS access rights.
+
+	:::php
+	class Category extends DataObject {
+	  // ...
+		public function canView($member = null) {
+			return Permission::check('CMS_ACCESS_CMSMain', 'any', $member);
+		}
+		public function canEdit($member = null) {
+			return Permission::check('CMS_ACCESS_CMSMain', 'any', $member);
+		}
+		public function canDelete($member = null) {
+			return Permission::check('CMS_ACCESS_CMSMain', 'any', $member);
+		}
+		public function canCreate($member = null) {
+			return Permission::check('CMS_ACCESS_CMSMain', 'any', $member);
+		}
+
 ## Search Fields
 
 ModelAdmin uses the `[SearchContext](/reference/searchcontext)` class to provide