robotsnoindex

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.

Temporary 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:

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":{
         "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:

FieldDescription
repoThe owner and name of the repository name in the form owner/repository.
privilegeThe privilege associated with the group.
groupThe profile associated with the group.
ownerAn account profile for the owner.
display_nameThe user-provided name associated with the account.
uuidUnique identifier for an account.
nicknameThe public-facing name, when display_name is not public.
account_idAtlassian account ID.
membersAn 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

repositoryThe repository to which the group has access.
ownerThe account profile of the owning group.
nameThe 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

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_idYesThe workspace ID.


GET a list of privileged groups for a repository

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_idYesThe workspace ID.
repo_slugYesA repository belonging to the account.

GET a group on a repository

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_idYesThe workspace ID.
repo_slugYesA repository belonging to the account.
group_ownerYesThe account that owns the group.
group_slugYesThe 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

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_idYesThe workspace ID.
group_ownerYesThe account that owns the group.
group_slugYesThe 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.

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

PUT group privileges on a repository

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_idYesThe workspace ID.
repo_slugYesThe repository to grant privileges on.
group_ownerYesThe account that owns the group.
group_slugYesThe 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.

$ 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

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_idYesThe workspace ID.
repo_slugYesThe repository to grant privileges on.
group_ownerYesThe account that owns the group.
group_slugYesThe 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.

$ 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

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_idYesThe workspace ID.
group_ownerYesThe account that owns the group.
group_slugYesThe 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:

$ 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.