---
layout: default
navsection: api
navmenu: Concepts
title: "Permission model"

...

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.

The Collections and the Group can only be seen by Alfred, administrators, and the system user.

The data in the Collections can only be retrieved by Alfred, administrators, and the system user.

h3. 2. Public objects

George creates a "PGP public data" Group, and grants "read" permission to all users.

* ...by adding a Link: "All users" Group _can_read_→ "PGP public data" Group

George stores 4 data Collections in Keep and adds them to the "PGP public data" Group

* ...by adding a Link: Group _can_read_→ Collection

Anyone who can connect to Arvados can log in with a Google/OpenID account and read the data.

h3. 3. Group-managed objects

Three lab members are working together on a project. All Specimens, Links, Jobs, etc. can be modified by any of the three lab members. _Other_ lab members, who are not working on this project, can view but not modify these objects.

h3. 4. Segregated roles

Granwyth, at the Hulatberi Lab, sets up a Factory Robot which uses a hosted Arvados site to do work for the Hulatberi Lab.

Frank uploads a data Collection using Factory Robot's upload interface.  Factory Robot sets data owner to Hulatberi Lab.

Factory Robot processes the data using a pipeline.

Factory Robot grants permission for anyone in the Ingeborg Lab (a Hulateberi Lab customer) to read the output of the pipeline, as well as the pipeline invocation details.  (Say, Ingeborg and Jill.)

During and after processing, all members of the Hulatberi Lab (_e.g._, Mike) can inspect pipeline progress, read source/intermediate/output data, and modify objects.

Possible encoding:

table(table table-bordered table-condensed).
|Tail           |Permission     |Head                      |Effect|
|Frank          |(none)         |                          |Factory Robot uses only its own credentials during upload|
|Granwyth       |can_manage     |User:    Factory Robot    |can revoke tokens, view activity... (needed?)|
|Granwyth       |can_manage     |Group: Hulatberi Lab    |can grant group-write permission to Factory Robot|
|Factory Robot  |can_write      |Group: Hulatberi Lab    |can add data, pipelines, jobs, etc. to the Lab group|
|Mike           |can_write      |Group: Hulatberi Lab    |can edit/annotate/delete objects that belong to the Lab|

h3. Actions governed by permissions

table(table table-bordered table-condensed).
|_Action_|_Permissions needed_|
|Retrieve data from Keep|can_read (system-wide?)|
|Store data in Keep|can_write (system-wide?)|
|Add a Collection to Arvados|can_write (system-wide?)|
|Run a job|can_run (system-wide?)|
|See progress/result of a job|can_read (on job)|
|Give group permissions to a user/group|can_manage (on group)|
|Revoke group permissions from a user/group|can_manage (on group)|
|Change owner of an object|can_manage (on object)|
|Add an object to a group|can_write (on group)|