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:

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

$ 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_id	Yes	The 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_id	Yes	The workspace ID.
repo_slug	Yes	A 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_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

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.

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

$ 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_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 mcatalbas/ developers 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_id

Yes

The workspace ID.

group_owner

Yes

The account that owns the group.

group_slug

Yes

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.

Was this helpful?

It wasn't accurate

It wasn't clear

It wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community