Documentation/rest-api-access.txt

= Gerrit Code Review - /access/ REST API

This page describes the access rights related REST endpoints.
Please also take note of the general information on the
link:rest-api.html[REST API].

[[access-endpoints]]
== Access Rights Endpoints

[[list-access]]
=== List Access Rights
--
'GET /access/?project=link:rest-api-projects.html#project-name[\{project-name\}]'
--

Lists the access rights for projects. The projects for which the access
rights should be returned must be specified as `project` options. The
`project` can be specified multiple times.

As result a map is returned that maps the project name to
link:#project-access-info[ProjectAccessInfo] entities.

The entries in the map are sorted by project name.

.Request
----
  GET /access/?project=MyProject&project=All-Projects HTTP/1.0
----

.Response
----
  HTTP/1.1 200 OK
  Content-Type: application/json; charset=UTF-8

  )]}'
  {
    "All-Projects": {
      "revision": "edd453d18e08640e67a8c9a150cec998ed0ac9aa",
      "local": {
        "GLOBAL_CAPABILITIES": {
          "permissions": {
            "priority": {
              "rules": {
                "15bfcd8a6de1a69c50b30cedcdcc951c15703152": {
                  "action": "BATCH"
                }
              }
            },
            "streamEvents": {
              "rules": {
                "15bfcd8a6de1a69c50b30cedcdcc951c15703152": {
                  "action": "ALLOW"
                }
              }
            },
            "administrateServer": {
              "rules": {
                "53a4f647a89ea57992571187d8025f830625192a": {
                  "action": "ALLOW"
                }
              }
            }
          }
        },
        "refs/meta/config": {
          "permissions": {
            "submit": {
              "rules": {
                "53a4f647a89ea57992571187d8025f830625192a": {
                  "action": "ALLOW"
                },
                "global:Project-Owners": {
                  "action": "ALLOW"
                }
              }
            },
            "label-Code-Review": {
              "label": "Code-Review",
              "rules": {
                "53a4f647a89ea57992571187d8025f830625192a": {
                  "action": "ALLOW",
                  "min": -2,
                  "max": 2
                },
                "global:Project-Owners": {
                  "action": "ALLOW",
                  "min": -2,
                  "max": 2
                }
              }
            },
            "read": {
              "exclusive": true,
              "rules": {
                "53a4f647a89ea57992571187d8025f830625192a": {
                  "action": "ALLOW"
                },
                "global:Project-Owners": {
                  "action": "ALLOW"
                }
              }
            },
            "push": {
              "rules": {
                "53a4f647a89ea57992571187d8025f830625192a": {
                  "action": "ALLOW"
                },
                "global:Project-Owners": {
                  "action": "ALLOW"
                }
              }
            }
          }
        },
        "refs/for/refs/*": {
          "permissions": {
            "pushMerge": {
              "rules": {
                "global:Registered-Users": {
                  "action": "ALLOW"
                }
              }
            },
            "push": {
              "rules": {
                "global:Registered-Users": {
                  "action": "ALLOW"
                }
              }
            }
          }
        },
        "refs/tags/*": {
          "permissions": {
            "createSignedTag": {
              "rules": {
                "53a4f647a89ea57992571187d8025f830625192a": {
                  "action": "ALLOW"
                },
                "global:Project-Owners": {
                  "action": "ALLOW"
                }
              }
            },
            "createTag": {
              "rules": {
                "53a4f647a89ea57992571187d8025f830625192a": {
                  "action": "ALLOW"
                },
                "global:Project-Owners": {
                  "action": "ALLOW"
                }
              }
            }
          }
        },
        "refs/heads/*": {
          "permissions": {
            "forgeCommitter": {
              "rules": {
                "53a4f647a89ea57992571187d8025f830625192a": {
                  "action": "ALLOW"
                },
                "global:Project-Owners": {
                  "action": "ALLOW"
                }
              }
            },
            "forgeAuthor": {
              "rules": {
                "global:Registered-Users": {
                  "action": "ALLOW"
                }
              }
            },
            "submit": {
              "rules": {
                "53a4f647a89ea57992571187d8025f830625192a": {
                  "action": "ALLOW"
                },
                "global:Project-Owners": {
                  "action": "ALLOW"
                }
              }
            },
            "editTopicName": {
              "rules": {
                "53a4f647a89ea57992571187d8025f830625192a": {
                  "action": "ALLOW",
                  "force": true
                },
                "global:Project-Owners": {
                  "action": "ALLOW",
                  "force": true
                }
              }
            },
            "label-Code-Review": {
              "label": "Code-Review",
              "rules": {
                "global:Registered-Users": {
                  "action": "ALLOW",
                  "min": -1,
                  "max": 1
                },
                "53a4f647a89ea57992571187d8025f830625192a": {
                  "action": "ALLOW",
                  "min": -2,
                  "max": 2
                },
                "global:Project-Owners": {
                  "action": "ALLOW",
                  "min": -2,
                  "max": 2
                }
              }
            },
            "create": {
              "rules": {
                "53a4f647a89ea57992571187d8025f830625192a": {
                  "action": "ALLOW"
                },
                "global:Project-Owners": {
                  "action": "ALLOW"
                }
              }
            },
            "push": {
              "rules": {
                "53a4f647a89ea57992571187d8025f830625192a": {
                  "action": "ALLOW"
                },
                "global:Project-Owners": {
                  "action": "ALLOW"
                }
              }
            }
          }
        },
        "refs/*": {
          "permissions": {
            "read": {
              "rules": {
                "global:Anonymous-Users": {
                  "action": "ALLOW"
                },
                "53a4f647a89ea57992571187d8025f830625192a": {
                  "action": "ALLOW"
                }
              }
            }
          }
        }
      },
      "is_owner": true,
      "owner_of": [
        "GLOBAL_CAPABILITIES",
        "refs/meta/config",
        "refs/for/refs/*",
        "refs/tags/*",
        "refs/heads/*",
        "refs/*"
      ],
      "can_upload": true,
      "can_add": true,
      "can_add_tags": true,
      "config_visible": true,
      "groups": {
         "53a4f647a89ea57992571187d8025f830625192a": {
           "url": "#/admin/groups/uuid-53a4f647a89ea57992571187d8025f830625192a",
           "options": {},
           "description": "Gerrit Site Administrators",
           "group_id": 1,
           "owner": "Administrators",
           "owner_id": "53a4f647a89ea57992571187d8025f830625192a",
           "created_on": "2009-06-08 23:31:00.000000000",
           "name": "Administrators"
         },
         "global:Registered-Users": {
           "options": {},
           "name": "Registered Users"
         },
         "global:Project-Owners": {
           "options": {},
           "name": "Project Owners"
         },
         "15bfcd8a6de1a69c50b30cedcdcc951c15703152": {
           "url": "#/admin/groups/uuid-15bfcd8a6de1a69c50b30cedcdcc951c15703152",
           "options": {},
           "description": "Service accounts that interact with Gerrit",
           "group_id": 2,
           "owner": "Administrators",
           "owner_id": "53a4f647a89ea57992571187d8025f830625192a",
           "created_on": "2009-06-08 23:31:00.000000000",
           "name": "Service Users"
         },
         "global:Anonymous-Users": {
           "options": {},
           "name": "Anonymous Users"
         }
      }
    },
    "MyProject": {
      "revision": "61157ed63e14d261b6dca40650472a9b0bd88474",
      "inherits_from": {
        "id": "All-Projects",
        "name": "All-Projects",
        "description": "Access inherited by all other projects."
      },
      "local": {},
      "is_owner": true,
      "owner_of": [
        "refs/*"
      ],
      "can_upload": true,
      "can_add": true,
      "can_add_tags": true,
      "config_visible": true
    }
  }
----

[[json-entities]]
== JSON Entities

[[access-section-info]]
=== AccessSectionInfo
The `AccessSectionInfo` describes the access rights that are assigned
on a ref.

[options="header",cols="1,^1,5"]
|==================================
|Field Name           ||Description
|`permissions`        ||
The permissions assigned on the ref of this access section as a map
that maps the permission names to link:#permission-info[PermissionInfo]
entities.
|==================================

[[permission-info]]
=== PermissionInfo
The `PermissionInfo` entity contains information about an assigned
permission.

[options="header",cols="1,^1,5"]
|==================================
|Field Name     ||Description
|`label`        |optional|
The name of the label. Not set if it's not a label permission.
|`exclusive`    |not set if `false`|
Whether this permission is assigned exclusively.
|`rules`        ||
The rules assigned for this permission as a map that maps the UUIDs of
the groups for which the permission are assigned to
link:#permission-info[PermissionRuleInfo] entities.
|==================================

[[permission-rule-info]]
=== PermissionRuleInfo
The `PermissionRuleInfo` entity contains information about a permission
rule that is assigned to group.

[options="header",cols="1,^1,5"]
|==================================
|Field Name     ||Description
|`action`       ||
The action of this rule. For normal permissions this can be `ALLOW`,
`DENY` or `BLOCK`. Special values for global capabilities are
`INTERACTIVE` and `BATCH`.
|`force`        |not set if `false`|
Whether the force flag is set.
|`min`          |
not set if range is empty (from `0` to `0`) or not set|
The min value of the permission range.
|`max`          |
not set if range is empty (from `0` to `0`) or not set|
The max value of the permission range.
|==================================

[[project-access-info]]
=== ProjectAccessInfo
The `ProjectAccessInfo` entity contains information about the access
rights for a project.

[options="header",cols="1,^1,5"]
|==================================
|Field Name           ||Description
|`revision`           ||
The revision of the `refs/meta/config` branch from which the access
rights were loaded.
|`inherits_from`      |not set for the `All-Projects` project|
The parent project from which permissions are inherited as a
link:rest-api-projects.html#project-info[ProjectInfo] entity.
|`local`              ||
The local access rights of the project as a map that maps the refs to
link:#access-section-info[AccessSectionInfo] entities.
|`is_owner`           |not set if `false`|
Whether the calling user owns this project.
|`owner_of`           ||The list of refs owned by the calling user.
|`can_upload`         |not set if `false`|
Whether the calling user can upload to any ref.
|`can_add`            |not set if `false`|
Whether the calling user can add any ref.
|`can_add_tags`       |not set if `false`|
Whether the calling user can add any tag ref.
|`config_visible`     |not set if `false`|
Whether the calling user can see the `refs/meta/config` branch of the
project.
|`groups`             ||A map of group UUID to
link:rest-api-groups.html#group-info[GroupInfo] objects, with names and
URLs for the group UUIDs used in the `local` map.
This will include names for groups that might
be invisible to the caller.
|`config_web_links`   |optional|
Links to the history of the configuration file governing this project's access
rights as list of link:rest-api-changes.html#web-link-info[WebLinkInfo]
entities.
|==================================


GERRIT
------
Part of link:index.html[Gerrit Code Review]

SEARCHBOX
---------