privileges Endpoint

Overview

Use the privileges endpoint to manage the 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://bitbucket.org/api/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://bitbucket.org/api/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://bitbucket.org/api/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://bitbucket.org/api/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://bitbucket.org/api/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/brodie with the string write as request body:

$ curl --request PUT --user evzijst:password https://bitbucket.org/api/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://bitbucket.org/api/1.0/privileges/evzijst/test/brodie --data read

PUT  https://bitbucket.org/api/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://bitbucket.org/api/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://bitbucket.org/api/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://bitbucket.org/api/1.0/privileges/{accountname}

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

Was this helpful?

Thanks for your feedback!

9 Archived comments

  1. User avatar

    Anonymous

    The api is not currently working, any request made to get privileges returns an empty array => [] 

    23 Jan 2013
    1. User avatar

      Luis Cipriani

      +1, please fix this!

      22 Feb 2013
      1. User avatar

        manthony

        Luis,

        What you are seeing is the expected behavior if there are no individual accounts granted privileges.  To get every access you need to make a call to this endpoint and the group-privileges Endpoint.  I've clarified the content to avoid this understandable confusion.

        Mary

        19 Jun 2013
  2. User avatar

    Rui Peres

    How is it possible to know who has read/write privileges in a repository? For example if I go to a public repository's issues, I am able to search for assigned. I guess the endpoint you are using is this one. But I am receiving the forbidden status (403). What can I do to know who can be assignable? 

     

    18 Jun 2013
    1. User avatar

      manthony

      Rui,

      A 403 status means that you do not have administrative rights on the repository your specified.  You can't see those unless you are a repo owner or admin.  

      Mary

      19 Jun 2013
  3. User avatar

    Babak Habibi

    Why isn't there an API to remove an individual user's privileges from all repositories in an account? I'm sure that's a very common use case, far more useful than the one that revokes all privileges from all users in all repositories!

    Our team has 750+ repositories, hard to manage individual permissions when users leave the team (of course using groups makes more sense, but there is no way to enforce that either)

    24 Jul 2014
    1. User avatar

      Babak Habibi

      and yes we could write a script to get a list of repositories and make subsequent calls per user/per repository but it would be good to see such a common use case covered...

      24 Jul 2014
    1. User avatar

      Dan Stevens [Atlassian]

      Hello Babak,

      Thanks for taking the time to comment. I have tried a couple different approaches with our existing API's and haven't found a better way to address this. So I'd like to ask you to open a feature request or support issue which will bring this directly to our development teams attention (which I will also do).

      Next I think managing users and repository access with groups is the best practice for a team like yours with so many repo's. I know that is not the perfect solution and that you can't exactly enforce that on such an expansive set of repo's (would mean enforcing with all your repo admin's as well as team admins not to add anyone to a repo, only add groups).

      I realize that's not the answer you're hoping for, however we are constantly working to make teams and groups more effective to manage permissions and access and it is better now and will get better still.

      Please do open a feature request and feel free to contact our support team at support@bitbucket.org.

      Thanks again for taking the time to comment, we do listen.

      Dan

      24 Jul 2014
      1. User avatar

        John Slee

        Dan, thanks for your considered response.

        The "revoke all privileges on all repositories" endpoint that Babak mentioned - does that revoke grants to groups as well as users?

        Something that revoked all non-group grants would be exactly what we want, I think, especially if (for audit purposes) it returned a list of affected users. We could set something up to invoke it every N minutes, endure the brief pain while the repo owners fix up their repos to use groups properly, and use it to raise alerts from that point on.

        24 Jul 2014
Powered by Confluence and Scroll Viewport