App password permissions needed for each API call?

[John Simpson]

I'm looking through the API documentation here: https://developer.atlassian.com/bitbucket/api/2/reference/

Is there a list of the exact permissions that a Bitbucket "App password" needs in order to use each API call? For example, if I want to use the "POST https://api.bitbucket.org/2.0/repositories/$owner/$slug/deploy-keys" call to add an SSH "deployment key" to a repo, what specific permission would the "app password" need to have?

If anything, I would think the necessary permissions should be listed on each API call's documentation page.

[Stephen Sifers]

Hello John,

This is an excellent question and can be often missed due to the placement of the required scopes of permissions in the documentation. For the endpoint you referenced, /2.0/repositories/{username}/{repo_slug}/deploy-keys, the required scopes for the app password would be as follows:

Required Scopes

• repository - Read your repositories
• repository:admin - Administer your repositories

Source documentation: /2.0/repositories/{username}/{repo_slug}/deploy-keys

The required scopes within the endpoints may be found right after the example from the method and right before the responses. These will allow you to know which application password or user token will require which permissions.

I hope this proves helpful and you’re able to set the permissions you need within minimal trial and error.

Regards,
Stephen Sifers

[John Simpson]

Is there a list of these "scopes", and do they correspond to the checkboxes on the Bitbucket "Add app password" screen? I'm guessing they do, but it might be helpful if the documentation made that clear, and/or add the scope names on the "Add app password" screen, maybe as grey text below the existing labels. Calling them "App password permissions" in one place, and "scopes" in another place, isn't the clearest thing in the world...

The original problem I ran into was this: I tried sending a "PUT /2.0/repositories/xxx/xxx/deploy-keys/xxx" request, using the same "Authorization: Basic xxx" header which works for other requests, and I was getting back a "400 Bad Request" with the message "That access key is invalid." HOWEVER, it turned out the problem was a missing "Content-Type" header.

So at the very least, the API server is returning the wrong error message.

What I'm running into now is, for the same request (and with the "Content-Type" header), I'm getting a 400 with the message "For security reasons, you can't modify the contents of an access key. To update, delete and re-add the key."

Since all I'm doing is updating the label and comment, should I maybe *not* send the key as part of the request body? Should I be sending the 'key' value with the original comment appended to the key? Something else?

Or if the message means what it seems to be saying, deployment keys can't be updated once they've been created. If so, then why does the "PUT /2.0/repositories/xxx/xxx/deploy-keys/xxx" call even exist in the first place?