Privileges

The bitbucket 'privileges' REST resource provides functionality for querying and manipulating the privileges (permissions) of your repositories. It allows you to grant specific users access to read, write and or administer your repositories.

Note that repository privileges can only be queried and modified by the repository's owner or by repository administrators.

Querying Privileges

$ curl --user evzijst:password https://api.bitbucket.org/1.0/privileges/evzijst/test
[
    {
        "repo": "evzijst/test",
        "privilege": "read",
        "user": {
            "username": "jespern",
            "first_name": "Jesper",
            "last_name": "Noehr"
        }
    },
    {
        "repo": "evzijst/test",
        "privilege": "read",
        "user": {
            "username": "detkin",
            "first_name": "Dylan",
            "last_name": "Etkin"
        }
    },
    {
        "repo": "evzijst/test",
        "privilege": "write",
        "user": {
            "username": "davidchambers",
            "first_name": "David",
            "last_name": "Chambers"
        }
    },
    {
        "repo": "evzijst/test",
        "privilege": "admin",
        "user": {
            "username": "nvenegas",
            "first_name": "Nicolas",
            "last_name": "Venegas"
        }
    }
]

The above command requests a list of all privileges on the evzijst/test repository. This is a private repository to which users jespern and detkin have read access, user davidchambers has write access, and nvenegas has full administrative privileges.

Querying can also be done on the individual role level, as well as for all repositories owned by a specific user.
For example, request the access level of user nvenegas on repository evzijst/test:

$ curl --user evzijst:password https://api.bitbucket.org/1.0/privileges/evzijst/test/nvenegas
[
    {
        "repo": "evzijst/test",
        "privilege": "admin",
        "user": {
            "username": "nvenegas",
            "first_name": "Nicolas",
            "last_name": "Venegas"
        }
    }
]

To list all privileges on all of evzijst's repositories, use /1.0/privileges/evzijst

Filters

You can use the filter=read|write|admin query parameter to limit your results to a specific role. To list everyone who has write access to my repo, I can run:

$ curl --user evzijst:password https://api.bitbucket.org/1.0/privileges/evzijst/test?filter=write
[
    {
        "repo": "evzijst/test",
        "privilege": "write",
        "user": {
            "username": "davidchambers",
            "first_name": "David",
            "last_name": "Chambers"
        }
    },
    {
        "repo": "evzijst/test",
        "privilege": "admin",
        "user": {
            "username": "nvenegas",
            "first_name": "Nicolas",
            "last_name": "Venegas"
        }
    }
]

Note that this result includes administrators, as they too have write access.

Granting Privileges

To grant user brodie write access to my repo, I can do a PUT on /1.0/privileges/evzijst/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

Upgrading or downgrading an existing user's privilege level is also done through this command. When the above command is run, brodie will have his "write" access modified to "read". Hence, a user can only have one access level, either "read", "write", or "admin".

Status Codes

401: Unauthorized

Returned if the requester does not have "admin" privileges for the repository.

403: Forbidden

Returned if the repo owner is at or over her account's private user limit when do a PUT (granting privileges to a new user).

404: Not Found

Returned if the specified resource does not exist.

Revoking Privileges

To revoke a user's privileges, simply do a DELETE. The following command revokes the privileges of user brodie:

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

To revoke all privileges on repo evzijst/test in one go, do:

$ curl --request DELETE --user evzijst:password https://api.bitbucket.org/1.0/privileges/evzijst/test

If you want, you can go even further and revoke all privileges on all of your own repositories at once:

$ curl --request DELETE --user evzijst:password https://api.bitbucket.org/1.0/privileges/evzijst

All deletes return a 200 status code and empty response body on success.

Bitbucket Documentation