Atlassian Bitbucket Teams API
The Atlassian Bitbucket Teams API provides access to team management features including repository management, branching, and team activity.
OpenAPI Specification
openapi: 3.0.0
info:
title: 'Atlassian teams/'
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:
/teams/{username}/pipelines_config/variables:
get:
tags:
- Pipelines
summary: Atlassian List Variables For An Account
deprecated: true
description: >-
Find account level variables.<br>This endpoint has been deprecated, and
you should use the new workspaces endpoint. For more information, see
[the
announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-teams-deprecation/).
operationId: atlassianGetpipelinevariablesforteam
parameters:
- name: username
description: The account.
required: true
in: path
schema:
type: string
responses:
'200':
description: The found account level variables.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_pipeline_variables'
security:
- oauth2:
- pipeline
- basic: []
- api_key: []
post:
tags:
- Pipelines
deprecated: true
summary: Atlassian Create A Variable For A User
description: >-
Create an account level variable.<br>This endpoint has been deprecated,
and you should use the new workspaces endpoint. For more information,
see [the
announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-teams-deprecation/).
operationId: atlassianCreatepipelinevariableforteam
parameters:
- name: username
description: The account.
required: true
in: path
schema:
type: string
requestBody:
$ref: '#/components/requestBodies/pipeline_variable2'
responses:
'201':
description: The created variable.
headers:
Location:
description: The URL of the newly created pipeline variable.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/pipeline_variable'
'404':
description: The account does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'409':
description: A variable with the provided key already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- pipeline:variable
- basic: []
- api_key: []
/teams/{username}/pipelines_config/variables/{variable_uuid}:
get:
tags:
- Pipelines
deprecated: true
summary: Atlassian Get A Variable For A Team
description: >-
Retrieve a team level variable.<br>This endpoint has been deprecated,
and you should use the new workspaces endpoint. For more information,
see [the
announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-teams-deprecation/).
operationId: atlassianGetpipelinevariableforteam
parameters:
- name: username
description: The account.
required: true
in: path
schema:
type: string
- name: variable_uuid
description: The UUID of the variable to retrieve.
required: true
in: path
schema:
type: string
responses:
'200':
description: The variable.
content:
application/json:
schema:
$ref: '#/components/schemas/pipeline_variable'
'404':
description: The account or variable with the given UUID was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- pipeline
- basic: []
- api_key: []
put:
tags:
- Pipelines
deprecated: true
summary: Atlassian Update A Variable For A Team
description: >-
Update a team level variable.<br>This endpoint has been deprecated, and
you should use the new workspaces endpoint. For more information, see
[the
announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-teams-deprecation/).
operationId: atlassianUpdatepipelinevariableforteam
parameters:
- name: username
description: The account.
required: true
in: path
schema:
type: string
- name: variable_uuid
description: The UUID of the variable.
required: true
in: path
schema:
type: string
requestBody:
$ref: '#/components/requestBodies/pipeline_variable'
responses:
'200':
description: The variable was updated.
content:
application/json:
schema:
$ref: '#/components/schemas/pipeline_variable'
'404':
description: The account or the variable was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- pipeline:variable
- basic: []
- api_key: []
delete:
tags:
- Pipelines
deprecated: true
summary: Atlassian Delete A Variable For A Team
description: >-
Delete a team level variable.<br>This endpoint has been deprecated, and
you should use the new workspaces endpoint. For more information, see
[the
announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-teams-deprecation/).
operationId: atlassianDeletepipelinevariableforteam
parameters:
- name: username
description: The account.
required: true
in: path
schema:
type: string
- name: variable_uuid
description: The UUID of the variable to delete.
required: true
in: path
schema:
type: string
responses:
'204':
description: The variable was deleted
'404':
description: The account or the variable with the provided UUID does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- pipeline:variable
- basic: []
- api_key: []
/teams/{username}/search/code:
get:
tags:
- Search
summary: Atlassian Search For Code In A Team S Repositories
description: >-
Search for code in the repositories of the specified team.<br><br>Note
that searches can match in the file's text (`content_matches`),<br>the
path (`path_matches`), or both.<br><br>You can use the same syntax for
the search query as in the UI.<br>E.g. to search for "foo" only within
the repository "demo",<br>use the query parameter
`search_query=foo+repo:demo`.<br><br>Similar to other APIs, you can
request more fields using a<br>`fields` query parameter. E.g. to get
some more information about<br>the repository of matched files, use the
query
parameter<br>`search_query=foo&fields=%2Bvalues.file.commit.repository`<br>(the
`%2B` is a URL-encoded `+`).<br><br>Try `fields=%2Bvalues.*.*.*.*` to
get an idea what's possible.<br>
operationId: atlassianSearchteam
parameters:
- name: username
in: path
description: >-
The account to search in; either the username or the UUID in curly
braces
required: true
schema:
type: string
- name: search_query
in: query
description: The search query
required: true
schema:
type: string
- name: page
in: query
description: Which page of the search results to retrieve
required: false
schema:
type: integer
format: int32
default: 1
- name: pagelen
in: query
description: How many search results to retrieve per page
required: false
schema:
type: integer
format: int32
default: 10
responses:
'200':
description: Successful search
content:
application/json:
schema:
$ref: '#/components/schemas/search_result_page'
examples:
response:
value:
size: 1
page: 1
pagelen: 10
query_substituted: false
values:
- type: code_search_result
content_match_count: 2
content_matches:
- lines:
- line: 2
segments: []
- line: 3
segments:
- text: 'def '
- text: foo
match: true
- text: '():'
- line: 4
segments:
- text: ' print("snek")'
- line: 5
segments: []
path_matches:
- text: src/
- text: foo
match: true
- text: .py
file:
path: src/foo.py
type: commit_file
links:
self:
href: >-
https://api.bitbucket.org/2.0/repositories/my-workspace/demo/src/ad6964b5fe2880dbd9ddcad1c89000f1dbcbc24b/src/foo.py
'400':
description: |
If the search request was invalid due to one of the
following reasons:
* the specified type of target account doesn''t match the actual
account type;
* malformed pagination properties;
* missing or malformed search query, in the latter case an error
key will be returned in `error.data.key` property.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: >-
Search is not enabled for the requested team, navigate to
[https://bitbucket.org/search](https://bitbucket.org/search) to turn
it on
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'429':
description: Too many requests, try again later
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- repository
- basic: []
- api_key: []
tags:
- name: Pipelines
- name: Search
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 t
# --- truncated at 32 KB (130 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-teams--openapi-original.yml