Atlassian Bitbucket Hook Events API
The Atlassian Bitbucket Hook Events API enables users to create webhooks in Bitbucket repositories to trigger custom actions whenever specific events occur.
OpenAPI Specification
openapi: 3.0.0
info:
title: 'Atlassian hook events/'
description: Needs description.
version: '2.0'
termsOfService: https://www.atlassian.com/legal/customer-agreement
contact:
name: Bitbucket Support
url: https://support.atlassian.com/bitbucket-cloud/
email: [email protected]
paths:
/hook_events/{subject_type}:
get:
tags:
- Webhooks
description: >-
Returns a paginated list of all valid webhook events for
the<br>specified entity.<br>**The team and user webhooks are deprecated,
and you should use workspace instead.<br>For more information, see [the
announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-teams-deprecation/).**<br><br>This
is public data that does not require any scopes or
authentication.<br><br>NOTE: The example response is a truncated
response object for the `workspace` `subject_type`.<br>We return the
same structure for the other `subject_type` objects.
summary: Atlassian List Subscribable Webhook Types
responses:
'200':
description: A paginated list of webhook types available to subscribe on.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_hook_events'
examples:
response:
value:
page: 1
pagelen: 30
size: 4
values:
- category: Repository
description: Whenever a repository push occurs
event: repo:push
label: Push
- category: Repository
description: Whenever a repository fork occurs
event: repo:fork
label: Fork
- category: Repository
description: Whenever a repository import occurs
event: repo:imported
label: Import
- category: Pull Request
label: Approved
description: When someone has approved a pull request
event: pullrequest:approved
'404':
description: If an invalid `{subject_type}` value was specified.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2: []
- basic: []
- api_key: []
operationId: atlassianListSubscribableWebhookTypes
parameters:
- name: subject_type
in: path
description: A resource or subject type.
required: true
schema:
type: string
enum:
- repository
- workspace
tags:
- name: Webhooks
x-revision: 3c039d08312e
x-atlassian-narrative:
documents:
- anchor: authentication
title: Authentication methods
description: How to authenticate API actions
icon: >-
data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxOTcuNjQ3MyAxODYuODEzOCI+CiAgPGRlZnM+CiAgICA8c3R5bGU+CiAgICAgIC5jbHMtMSB7CiAgICAgICAgaXNvbGF0aW9uOiBpc29sYXRlOwogICAgICB9CgogICAgICAuY2xzLTIgewogICAgICAgIGZpbGw6ICNkZTM1MGI7CiAgICAgIH0KCiAgICAgIC5jbHMtMyB7CiAgICAgICAgZmlsbDogI2ZmNTYzMDsKICAgICAgfQoKICAgICAgLmNscy00IHsKICAgICAgICBmaWxsOiAjZGZlMWU1OwogICAgICAgIG1peC1ibGVuZC1tb2RlOiBtdWx0aXBseTsKICAgICAgfQoKICAgICAgLmNscy01IHsKICAgICAgICBmaWxsOiAjZmFmYmZjOwogICAgICB9CgogICAgICAuY2xzLTYgewogICAgICAgIGZpbGw6ICNlYmVjZjA7CiAgICAgIH0KCiAgICAgIC5jbHMtNyB7CiAgICAgICAgZmlsbDogbm9uZTsKICAgICAgICBzdHJva2U6ICMwMDY1ZmY7CiAgICAgICAgc3Ryb2tlLW1pdGVybGltaXQ6IDEwOwogICAgICAgIHN0cm9rZS13aWR0aDogMnB4OwogICAgICB9CgogICAgICAuY2xzLTggewogICAgICAgIGZpbGw6ICM1ZTZjODQ7CiAgICAgIH0KCiAgICAgIC5jbHMtOSB7CiAgICAgICAgZmlsbDogIzI1Mzg1ODsKICAgICAgfQoKICAgICAgLmNscy0xMCB7CiAgICAgICAgZmlsbDogIzI2ODRmZjsKICAgICAgfQoKICAgICAgLmNscy0xMSB7CiAgICAgICAgZmlsbDogIzAwNjVmZjsKICAgICAgfQogICAgPC9zdHlsZT4KICA8L2RlZnM+CiAgPHRpdGxlPlNlY3VyaXR5IHdpdGggS2V5PC90aXRsZT4KICA8ZyBjbGFzcz0iY2xzLTEiPgogICAgPGcgaWQ9IkxheWVyXzIiIGRhdGEtbmFtZT0iTGF5ZXIgMiI+CiAgICAgIDxnIGlkPSJPYmplY3RzIj4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTIiIGQ9Ik00Mi4wNjcyLDBoLjYxMTRhOCw4LDAsMCwxLDgsOFYyMy4yMzM4YTAsMCwwLDAsMSwwLDBIMzQuMDY3MmEwLDAsMCwwLDEsMCwwVjhBOCw4LDAsMCwxLDQyLjA2NzIsMFoiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTIiIGQ9Ik0xMDguMjIsMGguNjExNGE4LDgsMCwwLDEsOCw4VjIzLjIzMzhhMCwwLDAsMCwxLDAsMEgxMDAuMjJhMCwwLDAsMCwxLDAsMFY4QTgsOCwwLDAsMSwxMDguMjIsMFoiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTIiIGQ9Ik0xNzQuMzcyMiwwaC42MTE0YTgsOCwwLDAsMSw4LDhWMjMuMjMzOGEwLDAsMCwwLDEsMCwwSDE2Ni4zNzIyYTAsMCwwLDAsMSwwLDBWOEE4LDgsMCwwLDEsMTc0LjM3MjIsMFoiLz4KICAgICAgICA8cmVjdCBjbGFzcz0iY2xzLTIiIHg9IjM0LjA2NzIiIHk9IjIzLjIzMzgiIHdpZHRoPSIxNjMuNTgiIGhlaWdodD0iMTYzLjU4Ii8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0yIiBkPSJNNDIuMDY3MiwwSDU5LjI5YTgsOCwwLDAsMSw4LDhWMjMuMjIyOGEwLDAsMCwwLDEsMCwwSDM0LjA2NzJhMCwwLDAsMCwxLDAsMFY4YTgsOCwwLDAsMSw4LThaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0yIiBkPSJNMTA3LjI0NTgsMGgxNy4yMjI4YTgsOCwwLDAsMSw4LDhWMjMuMjIyOGEwLDAsMCwwLDEsMCwwSDk5LjI0NThhMCwwLDAsMCwxLDAsMFY4YTgsOCwwLDAsMSw4LThaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0yIiBkPSJNMTcyLjQyNDQsMGgxNy4yMjI4YTgsOCwwLDAsMSw4LDhWMjMuMjIyOGEwLDAsMCwwLDEsMCwwSDE2NC40MjQ0YTAsMCwwLDAsMSwwLDBWOGE4LDgsMCwwLDEsOC04WiIvPgogICAgICAgIDxyZWN0IGNsYXNzPSJjbHMtMyIgeD0iMTcuNDU1OCIgeT0iMjMuMjMzOCIgd2lkdGg9IjE2My41OCIgaGVpZ2h0PSIxNjMuNTgiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTMiIGQ9Ik0yNS40NTU4LDBINDIuNjc4NmE4LDgsMCwwLDEsOCw4VjIzLjIyMjhhMCwwLDAsMCwxLDAsMEgxNy40NTU4YTAsMCwwLDAsMSwwLDBWOEE4LDgsMCwwLDEsMjUuNDU1OCwwWiIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtMyIgZD0iTTkwLjYzNDQsMGgxNy4yMjI4YTgsOCwwLDAsMSw4LDhWMjMuMjIyOGEwLDAsMCwwLDEsMCwwSDgyLjYzNDRhMCwwLDAsMCwxLDAsMFY4QTgsOCwwLDAsMSw5MC42MzQ0LDBaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0zIiBkPSJNMTU1LjgxMywwaDE3LjIyMjhhOCw4LDAsMCwxLDgsOFYyMy4yMjI4YTAsMCwwLDAsMSwwLDBIMTQ3LjgxM2EwLDAsMCwwLDEsMCwwVjhBOCw4LDAsMCwxLDE1NS44MTMsMFoiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTMiIGQ9Ik0yNS40NTU4LDBINDIuNjc4NmE4LDgsMCwwLDEsOCw4VjIzLjIyMjhhMCwwLDAsMCwxLDAsMEgxNy40NTU4YTAsMCwwLDAsMSwwLDBWOEE4LDgsMCwwLDEsMjUuNDU1OCwwWiIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtMyIgZD0iTTkwLjYzNDQsMGgxNy4yMjI4YTgsOCwwLDAsMSw4LDhWMjMuMjIyOGEwLDAsMCwwLDEsMCwwSDgyLjYzNDRhMCwwLDAsMCwxLDAsMFY4QTgsOCwwLDAsMSw5MC42MzQ0LDBaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0zIiBkPSJNMTU1LjgxMywwaDE3LjIyMjhhOCw4LDAsMCwxLDgsOFYyMy4yMjI4YTAsMCwwLDAsMSwwLDBIMTQ3LjgxM2EwLDAsMCwwLDEsMCwwVjhBOCw4LDAsMCwxLDE1NS44MTMsMFoiLz4KICAgICAgICA8cmVjdCBjbGFzcz0iY2xzLTIiIHg9IjM1Ljc1OTYiIHk9IjU2LjgwNjUiIHdpZHRoPSIzMy4yMjI4IiBoZWlnaHQ9IjE1LjYwMzgiLz4KICAgICAgICA8cmVjdCBjbGFzcz0iY2xzLTIiIHg9IjEzMS4yMDE2IiB5PSIxMzYuOTYxNSIgd2lkdGg9IjMzLjIyMjgiIGhlaWdodD0iMTUuNjAzOCIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtNCIgZD0iTTU3LjM3MDksNzEuNjAzNmg3MC43NWE5LDksMCwwLDEsOSw5djM1LjM3NDlhNDQuMzc0OCw0NC4zNzQ4LDAsMCwxLTQ0LjM3NDgsNDQuMzc0OGgwYTQ0LjM3NDgsNDQuMzc0OCwwLDAsMS00NC4zNzQ4LTQ0LjM3NDhWODAuNjAzNkE5LDksMCwwLDEsNTcuMzcwOSw3MS42MDM2WiIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtNSIgZD0iTTY2LjM3MSw2Ni42NjE3aDcwLjc1YTksOSwwLDAsMSw5LDl2MzUuMzc0OWE0NC4zNzQ4LDQ0LjM3NDgsMCwwLDEtNDQuMzc0OCw0NC4zNzQ4aDBBNDQuMzc0OCw0NC4zNzQ4LDAsMCwxLDU3LjM3MSwxMTEuMDM2NlY3NS42NjE3YTksOSwwLDAsMSw5LTlaIi8+CiAgICAgICAgPHBhdGggaWQ9Il9SZWN0YW5nbGVfIiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTYiIGQ9Ik02MS4zNzEsNjYuNjYxN2g3MC43NWE5LDksMCwwLDEsOSw5djM1LjM3NDlhNDQuMzc0OCw0NC4zNzQ4LDAsMCwxLTQ0LjM3NDgsNDQuMzc0OGgwQTQ0LjM3NDgsNDQuMzc0OCwwLDAsMSw1Mi4zNzEsMTExLjAzNjZWNzUuNjYxN0E5LDksMCwwLDEsNjEuMzcxLDY2LjY2MTdaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy03IiBkPSJNOTYuNzQ1OSwxNDcuNzQ0MWEzNi43NDg3LDM2Ljc0ODcsMCwwLDEtMzYuNzA3NC0zNi43MDc0Vjc4LjA1ODRhMy43MzMzLDMuNzMzMywwLDAsMSwzLjcyOS0zLjcyOWg2NS45NTYzYTMuNzMzMywzLjczMzMsMCwwLDEsMy43MjksMy43Mjl2MzIuOTc4NEEzNi43NDg2LDM2Ljc0ODYsMCwwLDEsOTYuNzQ1OSwxNDcuNzQ0MVoiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTQiIGQ9Ik0xMDAuNjg5MywxNjMuMzE2N1YxMTEuMDk3M2EzLjk0NDMsMy45NDQzLDAsMCwwLTcuODg4NywwdjUyLjIyYTIyLjUyNTIsMjIuNTI1MiwwLDAsMC0xOC41NDc5LDIyLjE0YzAsLjQ1Ni4wMTc4LjkwNzguMDQ0NywxLjM1NzFIODIuMjFjLS4wNDE0LS40NDc0LS4wNjg4LS44OTktLjA2ODgtMS4zNTcxYTE0LjYyLDE0LjYyLDAsMCwxLDE0LjU5NzQtMTQuNjA0MWwuMDA2MS4wMDA2LjAwNjgtLjAwMDdBMTQuNjIxMSwxNC42MjExLDAsMCwxLDExMS4zNSwxODUuNDU2NmMwLC40NTgxLS4wMjczLjkxLS4wNjg4LDEuMzU3MWg3LjkxMjhjLjAyNjktLjQ0OTMuMDQ0Ny0uOTAxMS4wNDQ3LTEuMzU3MUEyMi41MjU5LDIyLjUyNTksMCwwLDAsMTAwLjY4OTMsMTYzLjMxNjdaIi8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy0yIiB4PSIxNy40NTU4IiB5PSIzNi40NzAyIiB3aWR0aD0iMzMuMjIyOCIgaGVpZ2h0PSIxNS42MDM4Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy0yIiB4PSIxNy40NTU4IiB5PSIxNTguMTIxNyIgd2lkdGg9IjMzLjIyMjgiIGhlaWdodD0iMTUuNjAzOCIvPgogICAgICAgIDxyZWN0IGNsYXNzPSJjbHMtMiIgeD0iMTQ3LjgxMyIgeT0iMzYuNDcwMiIgd2lkdGg9IjMzLjIyMjgiIGhlaWdodD0iMTUuNjAzOCIvPgogICAgICAgIDxyZWN0IGNsYXNzPSJjbHMtMiIgeD0iMTUwLjA2NDMiIHk9IjE1Ny41NTEzIiB3aWR0aD0iMzMuMjIyOCIgaGVpZ2h0PSIxNS42MDM4Ii8+CiAgICAgICAgPHBhdGggaWQ9Il9QYXRoXyIgZGF0YS1uYW1lPSImbHQ7UGF0aCZndDsiIGNsYXNzPSJjbHMtOCIgZD0iTTEwNy41MjU0LDEwMS4wMDI3YTExLjc3OTQsMTEuNzc5NCwwLDEsMC0xOS44Niw4LjU1NDhBNC4wNDE3LDQuMDQxNywwLDAsMSw4OC44NSwxMTMuNjJsLTIuMTA0LDcuMjY4MWEzLDMsMCwwLDAsMi44ODE3LDMuODM0MmgxMi4yMzcxYTMsMywwLDAsMCwyLjg4MTctMy44MzQybC0yLjA5NTktNy4yNGE0LjA3NDMsNC4wNzQzLDAsMCwxLDEuMTgwOC00LjA5NDVBMTEuNzE3MiwxMS43MTcyLDAsMCwwLDEwNy41MjU0LDEwMS4wMDI3WiIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtOSIgZD0iTTEwNC43NDYxLDEyMC44ODc3bC0yLjA5NTktNy4yNGE0LjA3NDQsNC4wNzQ0LDAsMCwxLDEuMTgwOC00LjA5NDUsMTEuNzYyOSwxMS43NjI5LDAsMCwwLTUuMDYtMTkuOTMxMywxMS45MSwxMS45MSwwLDAsMC04Ljc5OCwxMC45OTQ5LDExLjcxODUsMTEuNzE4NSwwLDAsMCwzLjY5MjksOC45NDFBNC4wNDE2LDQuMDQxNiwwLDAsMSw5NC44NSwxMTMuNjJsLTMuMjE0LDExLjEwMjNoMTAuMjI4OEEzLDMsMCwwLDAsMTA0Ljc0NjEsMTIwLjg4NzdaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0xMCIgZD0iTTgxLjc5NzUsMTAwLjMxYTMuOTQzOSwzLjk0MzksMCwwLDAtMy45NDQzLTMuOTQ0M0g0MS4wNDE3YTMuOTQ0MywzLjk0NDMsMCwwLDAsMCw3Ljg4ODdINzcuODUzMkEzLjk0MzksMy45NDM5LDAsMCwwLDgxLjc5NzUsMTAwLjMxWiIvPgogICAgICAgIDxwYXRoIGlkPSJfUGF0aF8yIiBkYXRhLW5hbWU9IiZsdDtQYXRoJmd0OyIgY2xhc3M9ImNscy0xMSIgZD0iTTQxLjA0MTYsMTA0LjI1MzlIOTYuODUzMmEzLjk0NDMsMy45NDQzLDAsMCwwLDAtNy44ODg3SDQxLjA0MTZhMy45NDQzLDMuOTQ0MywwLDAsMCwwLDcuODg4N1oiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTEwIiBkPSJNODEuNzk3NSwxMDAuMzFhMy45NDM5LDMuOTQzOSwwLDAsMC0zLjk0NDMtMy45NDQzSDQxLjA0MTdhMy45NDQzLDMuOTQ0MywwLDAsMCwwLDcuODg4N0g3Ny44NTMyQTMuOTQzOSwzLjk0MzksMCwwLDAsODEuNzk3NSwxMDAuMzFaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0xMCIgZD0iTTIyLjQ5MzIsMTIyLjgwMjlBMjIuNDkyOSwyMi40OTI5LDAsMSwxLDQ0Ljk4NTgsMTAwLjMxLDIyLjUxODUsMjIuNTE4NSwwLDAsMSwyMi40OTMyLDEyMi44MDI5Wm0wLTM3LjA5NzJBMTQuNjA0MiwxNC42MDQyLDAsMSwwLDM3LjA5NzIsMTAwLjMxLDE0LjYyMDcsMTQuNjIwNywwLDAsMCwyMi40OTMyLDg1LjcwNTdaIi8+CiAgICAgIDwvZz4KICAgIDwvZz4KICA8L2c+Cjwvc3ZnPgo='
body: >2
The purpose of this section is to describe how to authenticate when
making API calls using the Bitbucket REST API.
--
* [Basic auth](#basic-auth)
* [Access Tokens](#access-tokens)
* [Repository Access Tokens](#repository-access-tokens)
* [Project Access Tokens](#project-access-tokens)
* [Workspace Access Tokens](#workspace-access-tokens)
* [App passwords](#app-passwords)
* [OAuth 2.0](#oauth-2-0)
* [Making requests](#making-requests)
* [Repository cloning](#repository-cloning)
* [Refresh tokens](#refresh-tokens)
* [Bitbucket OAuth 2.0 Scopes](#bitbucket-oauth-2-0-scopes)
* [Forge App Scopes](#forge-app-scopes)
### Basic auth
Basic HTTP Authentication as per
[RFC-2617](https://tools.ietf.org/html/rfc2617) (Digest not supported).
Note that Basic Auth is available only with username and [app
password](https://bitbucket.org/account/settings/app-passwords/) as
credentials.
### Access Tokens
Access Tokens are passwords (or tokens) that provide access to a
_single_ repository, project or workspace.
These tokens can authenticate with Bitbucket APIs for scripting, CI/CD
tools, Bitbucket Cloud-connected apps,
and Bitbucket Cloud integrations.
Access Tokens are linked to a repository, project, or workspace, not a
user account.
The level of access provided by the token is set when a repository, or
workspace admin creates it,
by setting permission scopes.
There are three types of Access Token:
* **Repository Access Tokens** can connect to a single repository,
preventing them from accessing any other repositories or workspaces.
* **Project Access Tokens** can connect to a single project, providing
access to any repositories within the project.
* **Workspace Access Tokens** can connect to a single workspace and have
access to any projects and repositories within that workspace.
When using Bitbucket APIs with an Access Token, the token will be
treated as the "user" in the
Bitbucket UI and Bitbucket logs. This includes when using the Access
Token to leave a comment on a pull request,
push a commit, or merge a pull request. The Bitbucket UI and API
responses will show the
Repository/Project/Workspace Access Token as a user. The username shown
in the Bitbucket UI is the Access
Token _name_, and a custom icon is used to differentiate it from a
regular user in the UI.
#### Considerations for using Access Tokens
* After creation, an Access Token can't be viewed or modified. The
token's name, created date,
last accessed date, and scopes are visible on the repository, project,
or workspace **Access Tokens** page.
* Access Tokens can access a limited set of Bitbucket's permission
scopes.
* Provided you set the correct permission scopes, you can use an Access
Token to clone (`repository`)
and push (`repository:write`) code to the token's repository or the
repositories the token can access.
* You can't use an Access Token to log into the Bitbucket website.
* Access Tokens don't require two-step verification.
* You can set permission scopes (specific access rights) for each Access
Token.
* You can't use an Access Token to manipulate or query repository,
project, or workspace permissions.
* Access Tokens are not listed in any repository or workspace permission
API response.
* Access Tokens are deactivated when deleting the resource tied to it (a
repository, project, or workspace).
Repository Access Tokens are also revoked when transferring the
repository to another workspace.
* Any content created by the Access Token will persist after the Access
Token has been revoked.
* Access Tokens can interact with branch restriction APIs, but the token
can't be configured as a user with merge access when using branch
restrictions.
There are some APIs which are inaccessible for Access Tokens, these are:
* [Add a repository deploy
key](/cloud/bitbucket/rest/api-group-deployments/#api-repositories-workspace-repo-slug-deploy-keys-post)
* [Update a repository deploy
key](/cloud/bitbucket/rest/api-group-deployments/#api-repositories-workspace-repo-slug-deploy-keys-key-id-put)
* [Delete a repository deploy
key](/cloud/bitbucket/rest/api-group-deployments/#api-repositories-workspace-repo-slug-deploy-keys-key-id-delete)
#### Repository Access Tokens
For details on creating, managing, and using Repository Access Tokens,
visit
[Repository Access
Tokens](https://support.atlassian.com/bitbucket-cloud/docs/repository-access-tokens/).
The available scopes for Repository Access Tokens are:
- [`repository`](#repository)
- [`repository:write`](#repository-write)
- [`repository:admin`](#repository-admin)
- [`repository:delete`](#repository-delete)
- [`pullrequest`](#pullrequest)
- [`pullrequest:write`](#pullrequest-write)
- [`webhook`](#webhook)
- [`pipeline`](#pipeline)
- [`pipeline:write`](#pipeline-write)
- [`pipeline:variable`](#pipeline-variable)
- [`runner`](#runner)
- [`runner:write`](#runner-write)
#### Project Access Tokens
For details on creating, managing, and using Project Access Tokens,
visit
[Project Access
Tokens](https://support.atlassian.com/bitbucket-cloud/docs/project-access-tokens/).
The available scopes for Project Access Tokens are:
- [`project`](#project)
- [`repository`](#repository)
- [`repository:write`](#repository-write)
- [`repository:admin`](#repository-admin)
- [`repository:delete`](#repository-delete)
- [`pullrequest`](#pullrequest)
- [`pullrequest:write`](#pullrequest-write)
- [`webhook`](#webhook)
- [`pipeline`](#pipeline)
- [`pipeline:write`](#pipeline-write)
- [`pipeline:variable`](#pipeline-variable)
- [`runner`](#runner)
- [`runner:write`](#runner-write)
#### Workspace Access Tokens
For details on creating, managing, and using Workspace Access Tokens,
visit
[Workspace Access
Tokens](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-tokens/).
The available scopes for Workspace Access Tokens are:
- [`project`](#project)
- [`project:admin`](#project-admin)
- [`repository`](#repository)
- [`repository:write`](#repository-write)
- [`repository:admin`](#repository-admin)
- [`repository:delete`](#repository-delete)
- [`pullrequest`](#pullrequest)
- [`pullrequest:write`](#pullrequest-write)
- [`webhook`](#webhook)
- [`account`](#account)
- [`pipeline`](#pipeline)
- [`pipeline:write`](#pipeline-write)
- [`pipeline:variable`](#pipeline-variable)
- [`runner`](#runner)
- [`runner:write`](#runner-write)
### App passwords
App passwords allow users to make API calls to their Bitbucket account
through apps such as Sourcetree.
Some important points about app passwords:
* You cannot view an app password or adjust permissions after you create
the app password. Because app passwords are encrypted on our database
and cannot be viewed by anyone. They are essentially designed to be
disposable. If you need to change the scopes or lost the password just
create a new one.
* You cannot use them to log into your Bitbucket account.
* You cannot use app passwords to manage team actions.
App passwords are tied to an individual account's credentials and should not be shared. If you're sharing your app password you're essentially giving direct, authenticated, access to everything that password has been scoped to do with the Bitbucket API's.
* You can use them for API call authentication, even if you don't have
two-step verification enabled.
* You can set permission scopes (specific access rights) for each app
password.
For details on creating, managing, and using App passwords, visit
[App
passwords](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/).
### OAuth 2.0
Our OAuth 2 implementation is merged in with our existing OAuth 1 in
such a way that existing OAuth 1 consumers automatically become
valid OAuth 2 clients. The only thing you need to do is edit your
existing consumer and configure a callback URL.
Once that is in place, you'll have the following 2 URLs:
https://bitbucket.org/site/oauth2/authorize
https://bitbucket.org/site/oauth2/access_token
For obtaining access/bearer tokens, we support three of RFC-6749's grant
flows, plus a custom Bitbucket flow for exchanging JWT tokens for access
tokens.
Note that Resource Owner Password Credentials Grant (4.3) is no longer
supported.
#### 1. Authorization Code Grant (4.1)
The full-blown 3-LO flow. Request authorization from the end user by
sending their browser to:
https://bitbucket.org/site/oauth2/authorize?client_id={client_id}&response_type=code
The callback includes the `?code={}` query parameter that you can swap
for an access token:
$ curl -X POST -u "client_id:secret" \
https://bitbucket.org/site/oauth2/access_token \
-d grant_type=authorization_code -d code={code}
#### 2. Implicit Grant (4.2)
This flow is useful for browser-based add-ons that operate without
server-side backends.
Request the end user for authorization by directing the browser to:
https://bitbucket.org/site/oauth2/authorize?client_id={client_id}&response_type=token
That will redirect to your preconfigured callback URL with a fragment
containing the access token
(`#access_token={token}&token_type=bearer`) where your page's js can
pull it out of the URL.
#### 3. Client Credentials Grant (4.4)
Somewhat like our existing "2-LO" flow for OAuth 1. Obtain an access
token that represents not an end user, but the owner of the
client/consumer:
$ curl -X POST -u "client_id:secret" \
https://bitbucket.org/site/oauth2/access_token \
-d grant_type=client_credentials
#### 4. Bitbucket Cloud JWT Grant (urn:bitbucket:oauth2:jwt)
If your Atlassian Connect add-on uses JWT authentication, you can swap a
JWT for an OAuth access token. The resulting access token represents the
account for which the add-on is installed.
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").
$ curl -X POST -H "Authorization: JWT {jwt_token}" \
https://bitbucket.org/site/oauth2/access_token \
-d grant_type=urn:bitbucket:oauth2:jwt
#### Making Requests
Once you have an access token, as per RFC-6750, you can use it in a
request in any of
the following ways (in decreasing order of desirability):
1. Send it in a request header: `Authorization: Bearer {access_token}`
2. Include it in a (application/x-www-form-urlencoded) POST body as
`access_token={access_token}`
3. Put it in the query string of a non-POST:
`?access_token={access_token}`
#### Repository Cloning
Since add-ons will not be able to upload their own SSH keys to clone
with, access tokens can be used as Basic HTTP Auth credentials to
clone securely over HTTPS. This is much like GitHub, yet slightly
different:
$ git clone https://x-token-auth:{access_token}@bitbucket.org/user/repo.git
The literal string `x-token-auth` as a substitute for username is
required (note the difference with GitHub where the actual token is in
the username field).
#### Refresh Tokens
Our access tokens expire in one hour. When this happens you'll get 401
responses.
Most access tokens grant responses (Implicit and JWT excluded).
Therefore, you should include a
refresh token that can then be used to generate a new access token,
without the need for end user participation:
$ curl -X POST -u "client_id:secret" \
https://bitbucket.org/site/oauth2/access_token \
-d grant_type=refresh_token -d refresh_token={refresh_token}
### Bitbucket OAuth 2.0 scopes
Bitbucket's API applies a number of privilege scopes to endpoints. In
order to access an endpoint, a request will need to have the necessary
scopes.
OAuth 2.0 Scopes are applicable for OAuth 2, Access Tokens, and App
passwords auth mechanisms as well as Bitbucket Connect apps.
Scopes are declared in the descriptor as a list of strings, with each
string being the name of a unique scope.
A descriptor lacking the `scopes` element is implicitly assumed to
require all scopes and as a result, Bitbucket will require end users
authorizing/installing the add-on
to explicitly accept all scopes.
Our best practice suggests you add only the scopes your add-on needs,
but no more than it needs.
Invalid scope strings will cause the descriptor to be rejected and the
installation to fail.
The available scopes are:
- [project](#project)
- [project:write](#project-write)
- [project:admin](#project-admin)
- [repository](#repository)
- [repository:write](#repository-write)
- [repository:admin](#repository-admin)
- [repository:delete](#repository-delete)
- [pullrequest](#pullrequest)
- [pullrequest:write](#pullrequest-write)
- [issue](#issue)
- [issue:write](#issue-write)
- [wiki](#wiki)
- [webhook](#webhook)
- [snippet](#snippet)
- [snippet:write](#snippet-write)
- [email](#email)
- [account](#account)
- [account:write](#account-write)
- [pipeline](#pipeline)
- [pipeline:write](#pipeline-write)
- [pipeline:variable](#pipeline-variable)
- [runner](#runner)
- [runner:write](#runner-write)
#### project
Provides access to view the project or projects.
This scope implies the [`repository`](#repository) scope, giving read
access to all the repositories in a project or projects.
#### project:write
This scope is deprecated, and has been made obsolete by `project:admin`.
Please see the deprecation notice
[here](/cloud/bitbucket/deprecation-notice-project-write-scope).
#### project:admin
Provides admin access to a project or projects. No distinction is made
between public and private projects. This scope doesn't implicitly grant
the [`project`](#project) scope or the
[`repository:write`](#repository-write) scope on any repositories under
the project. It gives access to the admin features of a project only,
not direct access to its repositories' contents.
* ability to create the project
* ability to update the project
* ability to delete the project
#### repository
Provides read access to a repository or repositories.
Note that this scope does not give access to a repository's pull
requests.
* access to the repo's source code
* clone over HTTPS
* access the file browsing API
* download zip archives of the repo's contents
* the ability to view and use the issue tracker on any repo (created
issues, comment, vote, etc)
* the ability to view and use the wiki on any repo (create/edit pages)
#### repository:write
Provides write (not admin) access to a repository or repositories. No
distinction is made between public and private repositories. This scope
implicitly grants the [`repository`](#repository) scope, which does not
need to be requested separately.
This scope alone does not give access to the pull requests API.
* push access over HTTPS
* fork repos
#### repository:admin
Provides admin access to a repository or repositories. No distinction is
made between public and private repositories. This scope doesn't
implicitly grant the [`repository`](#repository) or the
[`repository:write`](#repository-write) scopes. It gives access to the
admin features of a repo only, not direct access to its contents. This
scope can be used or misused to grant read access to other users, who
can then clone the repo, but users that need to read and write source
code would also request explicit read or write.
This scope comes with access to the following functionality:
* View and manipulate committer mappings
* List and edit deploy keys
* Ability to delete the repo
* View and edit repo permissions
* View and edit branch permissions
* Import and export the issue tracker
* Enable and disable the issue tracker
* List and edit issue tracker version, milestones and components
* Enable and disable the wiki
* List and edit default reviewers
* List and edit repo links (Jira/Bamboo/Custom)
* List and edit the repository webhooks
* Initiate a repo ownership transfer
#### repository:delete
Provides access to delete a repository or repositories.
#### pullrequest
Provides read access to pull requests.
This scope implies the [`repository`](#repository) scope, giving read
access to the pull request's destination repository.
* see and list pull requests
* create and resolve tasks
* comment on pull requests
#### pullrequest:write
Implicitly grants the [`pullrequest`](#pullrequest) scope and adds the
ability to create, merge and decline pull requests.
This scope also implicitly grants the
[`repository:write`](#repository-write) scope, giving write access to
the pull request's destination repository. This is necessary to allow
merging.
* merge pull requests
* decline pull requests
* create pull requests
* approve pull requests
#### issue
Ability to interact with issue trackers the way non-repo members can.
This scope doesn't implicitly grant any other scopes and doesn't give
implicit access to the repository.
* view, list and search issues
* create new issues
* comment on issues
* watch issues
* vote for issues
#### issue:write
This scope implicitly grants the [`issue`](#issue) scope and adds the
ability to transition and delete issues.
This scope doesn't implicitly grant any other scopes and doesn't give
implicit access to the repository.
* transition issues
* delete issues
#### wiki
Provides access to wikis. This scope provides both read and write access
(wikis are always editable by anyone with access to them).
This scope doesn't implicitly grant any other scopes and doesn't give
implicit access to the repository.
* view wikis
* create pages
* edit pages
* push to wikis
* clone wikis
#### webhook
Gives access to webhooks. This scope is required for any webhook-related
operation.
This scope gives read access to existing webhook subscriptions on all
resources the authorization mechanism can access, without needing
further scopes.
For example:
- A client can list all existing webhook subscriptions on a repository.
The [`repository`](#repository) scope is not required.
- Existing webhook subscriptions for the issue tracker on a repo can be
retrieved without the [`issue`](#issue) scope. All that is required is
the `webhook` scope.
To create webhooks, the client will need read access to the resource.
Such as: for [`issue:created`](#issue-created), the client will need to
have both the `webhook` and the [`issue`](#issue) scope.
* list webhook subscriptions on any accessible repository, user, team,
or snippet
* create/update/delete webhook subscriptions.
#### snippet
Provides read access to snippets.
No distinction is made betwee
# --- truncated at 32 KB (120 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-hook-events--openapi-original.yml