Get started with Bitbucket Cloud
New to Bitbucket Cloud? Check out our get started guides for new users.
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
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 |
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
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. |
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. |
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 |
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 |
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
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:
|
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
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 |
For example, the following call revokes the privileges of the group mcatalbas/ developers 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.
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 |
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.
Was this helpful?