If your Atlassian Connect app uses JWT authentication, you can swap a JWT for an OAuth access token. The resulting access token represents the account for which the app is installed. These OAuth tokens could, for example, be used to clone a repository.

Make sure you send the JWT token in the Authorization request header using the "JWT" scheme (case sensitive). Note that this custom scheme makes this different from HTTP Basic Auth (and so you cannot use "curl -u").

1
2
$ curl -X POST -H "Authorization: JWT {jwt_token}" \
  https://bitbucket.org/site/oauth2/access_token \
  -d grant_type=urn:bitbucket:oauth2:jwt

By default, these swapped OAuth tokens have the same scopes as the Connect app. However, you can also limit the scopes that will be applied for the swapped OAuth access token. The example below will swap a JWT for an OAuth token that will only have the repository:write scope. This assumes that the Connect app which issued the JWT had the repository:write scope.

1
2
$ curl -X POST -H "Authorization: JWT {jwt_token}" \
  https://bitbucket.org/site/oauth2/access_token \
  -d grant_type=urn:bitbucket:oauth2:jwt \
  -F scope=repository:write

In addition to limiting the scopes associated with the OAuth tokens, you can also limit the repositories to which the token applies. To achieve this, configure the form field bitbucket_repository and assign the UUID of the repository to which you want to limit the OAuth token to. Such limited OAuth tokens will only grant access to the specified repositories, and won't have any permissions on the workspace level.

1
2
$ curl -X POST -H "Authorization: JWT {jwt_token}" \
  https://bitbucket.org/site/oauth2/access_token \
  -d grant_type=urn:bitbucket:oauth2:jwt \
  -F bitbucket_repository={6662fce5-b95a-4905-a3a1-9d3d5560c17c}

The limiting of scopes and restricting repository access can be helpful to make Connect applications more secure. For example, if your Connect app executes a repository clone on remote servers, you can provide a clone token that gives the remote server read-only access to a specific repository.

Want a more in-depth example? Check out our bitbucket cloud JWT grant sample app.