group-privileges Endpoint

Overview

Use the group-privileges resource to query and manipulate the group privileges (permissions) of a Bitbucket Cloudaccount's repositories. An account owner (or team account administrator) defines groups at the account level. A group-privileges resource has the following structure:

{
        "repo": "1team/justdirectteam",
        "privilege": "admin",
        "group": {
            "owner": {
                "username": "1team",
                "first_name": "1 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/24b6be68b53e383c5d42bab4fe0bde2b?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "Administrators",
            "members": [
                {
                    "username": "nvenegas",
                    "first_name": "Nicolas",
                    "last_name": "Venegas"
                },
                {
                    "username": "brao",
                    "first_name": "Brodie",
                    "last_name": "Rao"
                }
            ],
            "slug": "administrators"
        },
        "repository": {
            "owner": {
                "username": "1team",
                "first_name": "1 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/24b6be68b53e383c5d42bab4fe0bde2b?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "justdirectteam",
            "slug": "justdirectteam"
        }
}

In the above example, the group Administrators has access to the justdirectteam repository.  The Administrators group has two members – nvenegas and brao.  The table below describes each field in the group-privileges resource:

Field Description
repo The owner and name of the repository name in the form owner/repository.
privilege The privilege associated with the group.
group The profile associated with the group.
owner An account profile for the owner.
name The displayed group name.
members An array of user account profiles. Each profile represents a single group member.
slug

The group identifier . The slug is an identifier constructed by the Bitbucket service. Bitbucket creates a slug by converting spaces to dashes and making all text lower case. So, if you name a group Viewer Release Management then its slug is:

viewer-release-management

repository The repository to which the group has access.
owner The account profile of the owning group.
name The displayed repository name.
slug

The repository identifier. The slug is an identifier constructed by the Bitbucket service. Bitbucket creates a slug by converting spaces to dashes and making all text lower case. So, if you name a repository My Cool Code then its slug is:

my-cool-code

Filtering to limit results

When using the GET methods on this resource, 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

You can use the private=true query parameter to filter for private repositories:

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

GET a list of privileged groups 

Gets an array of all the groups granted access to an account's repositories. The caller must authenticate as a user with administrative rights on the account. This method has the following parameters:

Parameter
Required?
Description
accountname Yes The team or individual account.
GET https://api.bitbucket.org/1.0/group-privileges/{accountname}
  Click to view the data returned on success...
$ 
[
    {
        "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"
        }
    }
]

GET a list of privileged groups for a repository

GET a list of the privilege groups for a specific repository. The caller must authenticate successfully and have administrative rights on the account. This method has the following parameters.

Parameter
Required?
Description
accountname Yes The team or individual account.
repo_slug Yes A repository belonging to the account.
GET https://api.bitbucket.org/1.0/group-privileges/{accountname}/{repo_slug}
  Click to view the data returned on success...
[
    {
        "repo": "2team/grouptest",
        "privilege": "read",
        "group": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "Contractors",
            "members": [],
            "slug": "contractors"
        },
        "repository": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "grouptest",
            "slug": "grouptest"
        }
    },
    {
        "repo": "2team/grouptest",
        "privilege": "admin",
        "group": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "Administrators",
            "members": [
                {
                    "username": "2team",
                    "first_name": "2 Team",
                    "last_name": "",
                    "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                    "is_team": true
                },
                {
                    "username": "buserbb",
                    "first_name": "B",
                    "last_name": "userbb",
                    "avatar": "https://secure.gravatar.com/avatar/b677e1e3bf1c781f852b288fd4b68480?d=identicon&s=32",
                    "is_team": false
                }
            ],
            "slug": "administrators"
        },
        "repository": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "grouptest",
            "slug": "grouptest"
        }
    },
    {
        "repo": "2team/grouptest",
        "privilege": "write",
        "group": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "Developers",
            "members": [
                {
                    "username": "buserbb",
                    "first_name": "B",
                    "last_name": "userbb",
                    "avatar": "https://secure.gravatar.com/avatar/b677e1e3bf1c781f852b288fd4b68480?d=identicon&s=32",
                    "is_team": false
                }
            ],
            "slug": "developers"
        },
        "repository": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "grouptest",
            "slug": "grouptest"
        }
    }
]
   

GET a group on a repository

Gets the privileges of a group on a repository.  The caller must authenticate as a user with administrative rights on the account. This method has the following parameters.

Parameter
Required?
Description
accountname Yes The team or individual account.
repo_slug Yes A repository belonging to the account.
group_owner Yes The account that owns the group.
group_slug Yes The group slug. The slug is an identifier constructed by the Bitbucket service. Bitbucket creates a slug by converting spaces to dashes and making all text lower case. So, if you name a group Viewer Release Management then its slug is:

viewer-release-management

GET  https://api.bitbucket.org/1.0/group-privileges/{accountname}/{repo_slug}/{group_owner}/{group_slug}
  Click here to expand...
[
    {
        "repo": "2team/grouptest",
        "privilege": "write",
        "group": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "Developers",
            "members": [
                {
                    "username": "buserbb",
                    "first_name": "B",
                    "last_name": "userbb",
                    "avatar": "https://secure.gravatar.com/avatar/b677e1e3bf1c781f852b288fd4b68480?d=identicon&s=32",
                    "is_team": false
                }
            ],
            "slug": "developers"
        },
        "repository": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "grouptest",
            "slug": "grouptest"
        }
    }
]

GET a list of repositories with a specific privilege group

Get a list of the repositories on which a particular privilege group appears.  This method operates on a single account, it does not list across acounts. The caller must authenticate as a user with administrative rights on the account. This method has the following parameters.

Parameter
Required?
Description
accountname Yes The team or individual account.
group_owner Yes The account that owns the group.
group_slug Yes The group slug. The slug is an identifier constructed by the Bitbucket service. Bitbucket creates a slug by converting spaces to dashes and making all text lower case. So, if you name a group Viewer Release Management then its slug is:

viewer-release-management

For example, the following call:

https://api.bitbucket.org/1.0/group-privileges/api/1.0/group-privileges/mcatalbas/mcatalbas/designers

Locates each repository owned by mcatalbas to which the group mcatalbas/designers has some level of access and lists the group's privileges in that repository.

GET https://api.bitbucket.org/1.0/group-privileges/{accountname}/{group_owner}/{group_slug}
  Click here to expand...
[
    {
        "repo": "2team/public2teamrepo",
        "privilege": "write",
        "group": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "Developers",
            "members": [
                {
                    "username": "buserbb",
                    "first_name": "B",
                    "last_name": "userbb",
                    "avatar": "https://secure.gravatar.com/avatar/b677e1e3bf1c781f852b288fd4b68480?d=identicon&s=32",
                    "is_team": false
                }
            ],
            "slug": "developers"
        },
        "repository": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "public2teamrepo",
            "slug": "public2teamrepo"
        }
    },
    {
        "repo": "2team/createdbyteamacct",
        "privilege": "write",
        "group": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "Developers",
            "members": [
                {
                    "username": "buserbb",
                    "first_name": "B",
                    "last_name": "userbb",
                    "avatar": "https://secure.gravatar.com/avatar/b677e1e3bf1c781f852b288fd4b68480?d=identicon&s=32",
                    "is_team": false
                }
            ],
            "slug": "developers"
        },
        "repository": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "createdbyteamacct",
            "slug": "createdbyteamacct"
        }
    },
    {
        "repo": "2team/teamproject",
        "privilege": "write",
        "group": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "Developers",
            "members": [
                {
                    "username": "buserbb",
                    "first_name": "B",
                    "last_name": "userbb",
                    "avatar": "https://secure.gravatar.com/avatar/b677e1e3bf1c781f852b288fd4b68480?d=identicon&s=32",
                    "is_team": false
                }
            ],
            "slug": "developers"
        },
        "repository": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "teamproject",
            "slug": "teamproject"
        }
    },
    {
        "repo": "2team/grouptest",
        "privilege": "write",
        "group": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "Developers",
            "members": [
                {
                    "username": "buserbb",
                    "first_name": "B",
                    "last_name": "userbb",
                    "avatar": "https://secure.gravatar.com/avatar/b677e1e3bf1c781f852b288fd4b68480?d=identicon&s=32",
                    "is_team": false
                }
            ],
            "slug": "developers"
        },
        "repository": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "grouptest",
            "slug": "grouptest"
        }
    }
]

PUT group privileges on a repository

Grant group privileges on a repository with a PUT method.  The caller must authenticate as a user with administrative rights on the account. This method has the following parameters.

Parameter
Required?
Description
accountname Yes The team or individual account.
repo_slug Yes The repository to grant privileges on.
group_owner Yes The account that owns the group.
group_slug Yes The group slug. The slug is an identifier constructed by the Bitbucket service. Bitbucket creates a slug by converting spaces to dashes and making all text lower case. So, if you name a group Viewer Release Managementthen its slug is:

viewer-release-management

privilege Yes

A privilege value, acceptable values are:

  • read
  • write
  • admin

For example, the following call:

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

This example adds the  mcatalbas/sys-admins group to the test repository with a privilege of read.

PUT https://api.bitbucket.org/1.0/group-privileges/{accountname}/{repo_slug}/{group_owner}/{group_slug} --data "{privilege}"
  Click to view the data returned on success...
[
    {
        "repo": "2team/grouptest",
        "privilege": "write",
        "group": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "Developers",
            "members": [
                {
                    "username": "buserbb",
                    "first_name": "B",
                    "last_name": "userbb",
                    "avatar": "https://secure.gravatar.com/avatar/b677e1e3bf1c781f852b288fd4b68480?d=identicon&s=32",
                    "is_team": false
                }
            ],
            "slug": "developers"
        },
        "repository": {
            "owner": {
                "username": "2team",
                "first_name": "2 Team",
                "last_name": "",
                "avatar": "https://secure.gravatar.com/avatar/15827007bdb707832ded90a612750cfb?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F6bc30a724121%2Fimg%2Fteam_no_avatar_32.png&s=32",
                "is_team": true
            },
            "name": "grouptest",
            "slug": "grouptest"
        }
    }
]

DELETE group privileges from a repository

DELETE a privilege group from a repository.  The caller must authenticate as a user with administrative rights on the account. This method has the following parameters:

Parameter
Required?
Description
accountname Yes The team or individual account.
repo_slug Yes The repository to grant privileges on.
group_owner Yes The account that owns the group.
group_slug Yes The group slug. The slug is an identifier constructed by the Bitbucket service. Bitbucket creates a slug by converting spaces to dashes and making all text lower case. So, if you name a group Viewer Release Management then its slug is:

viewer-release-management

For example, the following call:

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

Revokes the privileges of the group  mcatalbasdevelopers from the test repository.

DELETE https://api.bitbucket.org/1.0/group-privileges/{accountname}/{repo_slug}/{group_owner}/{group_slug} 

On success, this call returns HTTP/1.1 204 NO CONTENT.

DELETE privileges for a group across all your repositories

Deletes the privileges for a group on every repository where it appears.  The caller must authenticate as a user with administrative rights on the account. This method has the following parameters:

Parameter
Required?
Description
accountname Yes The team or individual account.
group_owner Yes The account that owns the group.
group_slug Yes The group slug. The slug is an identifier constructed by the Bitbucket service. Bitbucket creates a slug by converting spaces to dashes and making all text lower case. So, if you name a group Viewer Release Management then its slug is:

viewer-release-management

For example, the following call:

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

Revokes privileges of the group mtcatalbas/developers from all of mtcalbas' repositories:

DELETE https://api.bitbucket.org/1.0/group-privileges/{accountname}/group_owner}/{group_slug} 

This call returns a 200 status code and an empty response body on success.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport