group-privileges Endpoint

Bitbucket Cloud v1 APIs are deprecated

Bitbucket Cloud REST API version 1 is deprecated effective 30 June 2018, and were removed from the REST API permanently on 29 April 2019. Read the deprecation notice. Or you can jump right to the version 2.0 REST API documentation.

Temoporary support for limited 1.0 API resources

The 2.0 REST API will rely on the Atlassian Cloud Admin API for user and group management, but those API endpoints are not yet available. Until the Atlassian platform services are fully available in Bitbucket we will continue to support these 1.0 REST endpoints:

  • /1.0/groups

  • /1.0/group-privileges

  • /1.0/invitations

  • /1.0/users/{accountname}/invitations

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:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 { "repo":"1team/justdirectteam", "privilege":"admin", "group":{ "owner":{ "display_name":"1team", "uuid":"{c423e13e-b541-3e77-b363-3e0b458u8226}", "is_team":true, "mention_id":null, "avatar":"https://secure.gravatar.com/avatar/12e5043.png", "nickname":"1team", "account_id":null }, "name":"Administrators", "members":[ { "display_name":"Justen Stepka", "uuid":"{c423e13e-b541-3e77-b363-3e0b458u8226}", "is_team":false, "avatar":"https://secure.gravatar.com/avatar/12e5043", "nickname":"jstepka", "account_id":"557057:016ad873-3455-3455-23443-233534545434" } ], "slug":"administrators" }, "repository":{ "owner":{ "display_name":"Justen Stepka", "uuid":"{b8441b1d-a5e6-480a-ba0b-fde829182e4a}", "is_team":true, "mention_id":null, "avatar":"https://secure.gravatar.com/avatar/12e5043", "nickname":"supertesterteam", "account_id":null }, "name":"justdirectteam", "slug":"justdirectteam" } }

In the above example, the group Administrators has access to the justdirectteam repository.  The Administrators group has one member – jstepka.  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.

display_name

The user-provided name associated with the account.

uuid

Unique identifier for an account.

nickname

The public-facing name, when display_name is not public.

account_id

Atlassian account ID.

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:

1 $ 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:

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

GET a list of privileged groups

1 GET https://api.bitbucket.org/1.0/group-privileges/{workspace_id}

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

workspace_id

Yes

The workspace ID.


GET a list of privileged groups for a repository

1 GET https://api.bitbucket.org/1.0/group-privileges/{workspace_id}/{repo_slug}

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

workspace_id

Yes

The workspace ID.

repo_slug

Yes

A repository belonging to the account.

GET a group on a repository

1 GET https://api.bitbucket.org/1.0/group-privileges/{workspace_id}/{repo_slug}/{group_owner}/{group_slug}

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

workspace_id

Yes

The workspace ID.

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 a list of repositories with a specific privilege group

1 GET https://api.bitbucket.org/1.0/group-privileges/{workspace_id}/{group_owner}/{group_slug}

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 accounts. The caller must authenticate as a user with administrative rights on the account. This method has the following parameters.

Parameter

Required?

Description

workspace_id

Yes

The workspace ID.

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

Example

For example, the following call 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.

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

PUT group privileges on a repository

1 PUT https://api.bitbucket.org/1.0/group-privileges/{workspace_id}/{repo_slug}/{group_owner}/{group_slug} --data "{privilege}"

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

workspace_id

Yes

The workspace ID.

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

Example

For example, the following call adds the  mcatalbas/sys-admins group to the test repository with a privilege of read.

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

DELETE group privileges from a repository

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

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

workspace_id

Yes

The workspace ID.

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

Example

For example, the following call revokes the privileges of the group  mcatalbasdevelopers from the test repository.

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

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

DELETE privileges for a group across all your repositories

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

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

workspace_id

Yes

The workspace ID.

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

Example

For example, the following call revokes privileges of the group mtcatalbas/developers from all of mtcalbas' repositories:

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

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

Additional Help