privileges Endpoint

Overview

Use the privileges endpoint to manage Bitbucket Cloud user privileges (permissions). It allows you to grant specific users access to read, write and or administer your repositories. Only the repository owner, a team account administrator, or an account with administrative rights on the repository can can query or modify repository privileges. To manage group access to your repositories, use the group-privileges Endpoint and to manage privilege settings for team accounts, use the privileges Resource.  

The privileges endpoint has the following structure:

The fields in the privileges structure are the following:

Field Description
repo

The identifier for the repo in the format:

{owner}/{repo_slug}
privilege

The permission granted to the user. This is one of:

  • admin
  • read
  • write
user A user profile.
repository A repository profile.

To obtain a list of teams you are a member of, query the  /user/privileges  endpoint.  To list groups with access, see group-privileges Endpoint.

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/privileges/mcatalbas/?filter=admin

If you filter for the read permission, you also get the higher levels of permission such as write and admin as they also include the ability to read.

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/privileges/mcatalbas/?private=true

GET a list of individual user privileges granted on a repository

Gets a list of the privileges granted on a repository.  Only the repository owner, a team account administrator, or an account with administrative rights on the repository can make this call.  If a repository has no individual users with privileges, the method returns an [] empty array.  To get privileges for groups, use the group-privileges Endpoint.

This method has the following parameters:

Parameter
Required?
Description
accountname Yes Owner of the repository.
repo_slug Yes Repository identifier.
filter No

Filters for a particular privilege.  The acceptable values are:

  • read
  • write
  • admin

Lower level privileges encompass the higher levels; admin and write already have read access. To see every individual account with any access, specify the read filter.

GET https://api.bitbucket.org/1.0/privileges/{accountname}/{repo_slug}
  Click here to expand...

In the code below, the users jespern and detkin have read access, user davidchambers has write access, and nvenegas has full administrative privileges.

GET privileges for an individual

Get a list of privileges for an individual account. Only the repository owner, a team account administrator, or an account with administrative rights on the repository can make this call. This method has the following parameters:

Parameter
Required?
Description
accountname Yes Owner of the repository.
repo_slug Yes Repository identifier.
privilege_account Yes The account to list privileges for.
GET https://api.bitbucket.org/1.0/privileges/{accountname}/{repo_slug}/{privilege_account}
  Click here to expand...

GET a list of all privileges across all an account's repositories

Gets a list of all the privilege across all an account's repositories. If a repository has no individual users with privileges, it does not appear in this list. Only the repository owner, a team account administrator, or an account with administrative rights on the repository can make this call. This method has the following parameters:

Parameter
Required?
Description
accountname Yes Owner of the repository.
filter No

Filters for a particular privilege.  The acceptable values are:

  • read
  • write
  • admin
GET https://api.bitbucket.org/1.0/privileges/{accountname}
  Click here to expand...

PUT a new privilege

Grants an account a privilege on a repository. You can upgrade or downgrade a user's permissions with this method. Only the repository owner, a team account administrator, or an account with administrative rights on the repository can make this call. This method has the following parameters:

Parameter
Required?
Description
accountname Yes Owner of the repository.
repo_slug Yes Repository identifier.
group_slug Yes The group's slug.
privilege_account Yes The account to list privileges for.
privilege Yes

The privilege to assign.  Valid values are:

  • read
  • write
  • admin

To grant user brodie write access to the test repo,  PUT on /1.0/privileges/evzijst/test/brodie with the string write as request body:

$ curl --request PUT --user evzijst:password https://api.bitbucket.org/1.0/privileges/evzijst/test/brodie --data write

This will return a 200 status code on success, with an empty response body.

$ curl --request PUT --user evzijst:password https://api.bitbucket.org/1.0/privileges/evzijst/test/brodie --data read

PUT  https://api.bitbucket.org/1.0/privileges/{accountname}/{repo_slug}/{privilege_account} --data {read}
  Click here to expand...

DELETE account privileges from a repository

Delete an account's privileges from a repository. Only the repository owner, a team account administrator, or an account with administrative rights on the repository can make this call. This method has the following parameters:

Parameter
Required?
Description
accountname Yes Owner of the repository.
repo_slug Yes Repository identifier.
privilege_account Yes The account to list privileges for.
DELETE  https://api.bitbucket.org/1.0/privileges/{accountname}/{repo_slug}/{privilege_account}

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

DELETE all privileges from a repository  

Delete all privileges from a repository. Only the repository owner, a team account administrator, or an account with administrative rights on the repository can make this call. This method has the following parameters:  

Parameter
Required?
Description
accountname Yes Owner of the repository.
repo_slug Yes Repository identifier.
 
DELETE  https://api.bitbucket.org/1.0/privileges/{accountname}/{repo_slug}
  On success, this call returns HTTP/1.1 204 NO CONTENT.

DELETE all privileges from all repositories  

DELETE an privileges from all repositories. Only the repository owner, a team account administrator, or an account with administrative rights on the repository can make this call. This method has the following parameters:

Parameter
Required?
Description
accountname Yes Owner of the repositories.
DELETE  https://api.bitbucket.org/1.0/privileges/{accountname}

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

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