Groups Privileges

The bitbucket 'groups privileges' REST resource provides functionality for querying and manipulating the group privileges (permissions) of your repositories.

Querying for Privileges

$ curl --user mcatalbas:password -X GET https://api.bitbucket.org/1.0/group-privileges/mcatalbas/test/
[
    {
        "repo": "mcatalbas/test",
        "privilege": "write",
        "group": {
            "owner": {
                "username": "mcatalbas",
                "first_name": "Mehmet",
                "last_name": "Catalbas"
            },
            "name": "developers",
            "members": [
                {
                    "username": "nvenegas",
                    "first_name": "Nicolas",
                    "last_name": "Venegas"
                },
                {
                    "username": "brao",
                    "first_name": "Brodie",
                    "last_name": "Rao"
                }
            ],
            "slug": "developers"
        },
        "repository": {
            "owner": {
                "username": "mcatalbas",
                "first_name": "Mehmet",
                "last_name": "Catalbas"
            },
            "name": "test",
            "slug": "test"
        }
    },
    {
        "repo": "mcatalbas/test",
        "privilege": "admin",
        "group": {
            "owner": {
                "username": "mcatalbas",
                "first_name": "Mehmet",
                "last_name": "Catalbas"
            },
            "name": "managers",
            "members": [
                {
                    "username": "detkin",
                    "first_name": "Dylan",
                    "last_name": "Etkin"
                },
                {
                    "username": "jnoehr",
                    "first_name": "Jesper",
                    "last_name": "Noehr"
                }
            ],
            "slug": "managers"
        },
        "repository": {
            "owner": {
                "username": "mcatalbas",
                "first_name": "Mehmet",
                "last_name": "Catalbas"
            },
            "name": "test",
            "slug": "test"
        }
    }
]

The command above request a list of all privileges for the mcatalbas/test repository. The result shows that the group developers has write access and the group managers has admin access to the repository.

The reason for having both repo and repository objects is to remain consistent with the Privileges REST API. repo will most likely to be removed in the future, and repository will be the only object representing a repository.

You can also use other account owner's groups that you are a member of when querying and manipulating privileges of your own repositories. For example, to query mcatalbas's repository bugfix-331, for the account owner's atlassian group staff memberships details:

$ curl --request GET --user mcatalbas:password https://api.bitbucket.org/1.0/group-privileges/mcatalbas/bugfix-331/atlassian/developers
[
    {
        "repo": "mcatalbas/bugfix-331",
        "privilege": "write",
        "group": {
            "owner": {
                "username": "atlassian",
                "first_name": "",
                "last_name": ""
            },
            "name": "staff",
            "members": [
                {
                    "username": "nvenegas",
                    "first_name": "Nicolas",
                    "last_name": "Venegas"
                },
                {
                    "username": "brao",
                    "first_name": "Brodie",
                    "last_name": "Rao"
                }
            ],
            "slug": "staff"
        },
        "repository": {
            "owner": {
                "username": "mcatalbas",
                "first_name": "Mehmet",
                "last_name": "Catalbas"
            },
            "name": "bugfix-331",
            "slug": "bugfix-331"
        }
    }
]

List All Privileges

$ curl --request GET --user mcatalbas:password https://api.bitbucket.org/1.0/group-privileges/mcatalbas/

Filters

You can use the filter=read|write|admin query parameter to limit your results to a specific privilege level:

$ curl --request GET --user mcatalbas:password https://api.bitbucket.org/1.0/group-privileges/mcatalbas/?filter=admin

The private=true query parameter can be used to only include private repositories:

$ curl --request GET --user mcatalbas:password https://api.bitbucket.org/1.0/group-privileges/mcatalbas/?private=true

Granting Privileges

To grant the group mcatalbas/sys-admins read only access to the repository mcatalbas/test:

$ curl --request PUT --user mcatalbas:password https://api.bitbucket.org/1.0/group-privileges/mcatalbas/test/mcatalbas/sys-admins --data read

Status Codes

401: Unauthorized

Returned if the requester does not have "admin" privileges for the repository.

403: Forbidden

Returned if the repository owner is at or over the user limit when performing a PUT operation, e.g. granting privileges to a group.

404: Not Found

Returned if the specified group does not exist.

Revoking Privileges

To revoke privileges of the group developers (of mcatalbas') from the repository test (of mcatalbas'):

$ curl --request DELETE --user mcatalbas:password https://api.bitbucket.org/1.0/group-privileges/mcatalbas/test/mcatalbas/developers

To revoke privileges of the group developers from all of your repositories:

$ curl --request DELETE --user mcatalbas:password https://api.bitbucket.org/1.0/group-privileges/mcatalbas/mcatalbas/developers

All deletes return a 200 status code and an empty response body on success.

Bitbucket Documentation