-h1. Permission model
-
-Each API transaction (read, write, create, etc.) is done on behalf of a person.
-
-* An end user, via a web app
-* The owner of an installed app
-
-A user (person) is permitted to act on an object if there is a path (series of permission Links) from the acting user to the object in which
-
-* Every intervening object is a Group, and
-* Every intervening permission Link allows the current action
-
-Each object has exactly one _owner_, which can be either a User or a Group.
-
-* If the owner of X is A, then A is permitted to do any action on X.
-
-h3. Tokens
-
-An authorization token is issued at a user's request, and supplied to an API client using some suitable mechanism (_e.g._, cookie or application config file for a web app; environment variable or .rc-file for a CLI app).
-
-A user can have multiple valid tokens at a given time. At the user's option, a token can be restricted to a combination of
-
-* API client program
-* time interval
-* transaction type
-
-h3. System pseudo-user
-
-A privileged user account exists for the use of built-in Arvados system components. This user manages system-wide shared objects which can't really be "owned" by any particular user, like
-
-* Jobs and job steps (because a given job can be "wanted" by multiple users)
-* Provenance metadata (because no user should be able to modify this directly)
-* Storage metadata like
-** redundancy verified as N× at time Y
-** contents of collections A and B are identical
-
-The system pseudo-user's uuid is @{siteprefix}-tpzed-000000000000000@.
-
-h2. Example scenarios
-
-h3. 1. Private objects
-
-Alfred stores 3 data Collections in Keep and adds them to a new Group.
+* There are four levels of permission: *none*, *can_read*, *can_write*, and *can_manage*.
+** *none* is the default state when there are no other permission grants.
+*** the object is not included in any list query response.
+*** direct queries of the object by uuid return 404 Not Found.
+*** Link objects require valid identifiers in @head_uuid@ and @tail_uuid@, so an attempt to create a Link that references an unreadable object will return an error indicating the object is not found.
+** *can_read* grants read-only access to the record. Attempting to update or delete the record returns an error. *can_read* does not allow a reader to see any permission grants on the object except the object's owner_uuid and the reader's own permissions.
+** *can_write* permits changes to the record (but not permission links). *can_write* permits the user to delete the object. *can_write* also implies *can_read*.
+** *can_manage* permits the user to read, create, update and delete permission links whose @head_uuid@ is this object's @uuid@. *can_manage* also implies *can_write* and *can_read*.