Atlassian Bitbucket User API
The Atlassian Bitbucket User API allows developers to interact with and manage user accounts within the Bitbucket platform.
OpenAPI Specification
openapi: 3.0.0
info:
title: 'Atlassian user'
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:
/repositories/{workspace}/{repo_slug}/permissions-config/users:
get:
tags:
- Repositories
description: >-
Returns a paginated list of explicit user permissions for the given
repository.<br>This endpoint does not support BBQL features.
summary: Atlassian List Explicit User Permissions For A Repository
responses:
'200':
description: Paginated of explicit user permissions on the repository.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_repository_user_permissions'
examples:
response:
value:
pagelen: 10
values:
- type: repository_user_permission
user:
type: user
display_name: Colin Cameron
uuid: '{d301aafa-d676-4ee0-88be-962be7417567}'
account_id: 557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
permission: admin
links:
self:
href: >-
https://api.bitbucket.org/2.0/repositories/atlassian_tutorial/geordi/permissions-config/users/557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
- type: repository_user_permission
user:
type: user
display_name: Sean Conaty
uuid: '{504c3b62-8120-4f0c-a7bc-87800b9d6f70}'
account_id: 557058:ba8948b2-49da-43a9-9e8b-e7249b8e324c
permission: write
links:
self:
href: >-
https://api.bitbucket.org/2.0//repositories/atlassian_tutorial/geordi/permissions-config/users/557058:ba8948b2-49da-43a9-9e8b-e7249b8e324c
page: 1
size: 2
'401':
description: The user couldn't be authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: The requesting user isn't an admin of the repository.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: No repository exists for the given repository slug and workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:repository:bitbucket
- read:user:bitbucket
operationId: atlassianListExplicitUserPermissionsForARepository
parameters:
- name: repo_slug
in: path
description: |
This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
required: true
schema:
type: string
- name: workspace
in: path
description: |
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
required: true
schema:
type: string
/repositories/{workspace}/{repo_slug}/permissions-config/users/{selected_user_id}:
delete:
tags:
- Repositories
description: >-
Deletes the repository user permission between the requested repository
and user, if one exists.<br><br>Only users with admin permission for the
repository may access this resource.<br><br>The only authentication
method for this endpoint is via app passwords.
summary: Atlassian Delete An Explicit User Permission For A Repository
responses:
'204':
description: The repository user permission was deleted and no content returned.
'401':
description: The user couldn't be authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: >-
The requesting user isn't an admin of the repository, or the
authentication method was not via app password.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: >-
One or more of the workspace, repository, and user doesn't exist for
the given identifiers.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
operationId: atlassianDeleteAnExplicitUserPermissionForARepository
get:
tags:
- Repositories
description: >-
Returns the explicit user permission for a given user and
repository.<br><br>Only users with admin permission for the repository
may access this resource.<br><br>Permissions can be:<br><br>*
`admin`<br>* `write`<br>* `read`<br>* `none`
summary: Atlassian Get An Explicit User Permission For A Repository
responses:
'200':
description: Explicit user permission for user and repository
content:
application/json:
schema:
$ref: '#/components/schemas/repository_user_permission'
examples:
response:
value:
type: repository_user_permission
user:
type: user
display_name: Colin Cameron
uuid: '{d301aafa-d676-4ee0-88be-962be7417567}'
account_id: 557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
nickname: Colin Cameron
permission: admin
links:
self:
href: >-
https://api.bitbucket.org/2.0/repositories/atlassian_tutorial/geordi/permissions-config/users/557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
'401':
description: The user couldn't be authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: The requesting user isn't an admin of the repository.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: >-
One or both of the workspace and repository doesn't exist for the
given identifiers.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:repository:bitbucket
- read:user:bitbucket
operationId: atlassianGetAnExplicitUserPermissionForARepository
put:
tags:
- Repositories
description: >-
Updates the explicit user permission for a given user and repository.
The selected user must be a member of<br>the workspace, and cannot be
the workspace owner.<br>Only users with admin permission for the
repository may access this resource.<br><br>The only authentication
method for this endpoint is via app passwords.<br><br>Permissions can
be:<br><br>* `admin`<br>* `write`<br>* `read`
summary: Atlassian Update An Explicit User Permission For A Repository
responses:
'200':
description: Explicit user permission updated
content:
application/json:
schema:
$ref: '#/components/schemas/repository_user_permission'
examples:
response:
value:
type: repository_user_permission
user:
type: user
display_name: Colin Cameron
uuid: '{d301aafa-d676-4ee0-88be-962be7417567}'
account_id: 557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
nickname: Colin Cameron
permission: write
links:
self:
href: >-
https://api.bitbucket.org/2.0/repositories/atlassian_tutorial/geordi/permissions-config/users/557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
'400':
description: >-
No permission value was provided or the value is invalid (not one of
read, write, or admin), or the selected user is not a valid user to
update.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'401':
description: The user couldn't be authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'402':
description: >-
You have reached your plan's user limit and must upgrade before
giving access to additional users.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: >-
The requesting user isn't an admin of the repository, or the
authentication method was not via app password.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: >-
One or more of the workspace, repository, and selected user doesn't
exist for the given identifiers.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
requestBody:
$ref: >-
#/components/requestBodies/bitbucket.apps.permissions.serializers.RepoPermissionUpdateSchema
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
operationId: atlassianUpdateAnExplicitUserPermissionForARepository
parameters:
- name: repo_slug
in: path
description: |
This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
required: true
schema:
type: string
- name: selected_user_id
in: path
description: >
This can either be the UUID of the account, surrounded by
curly-braces, for
example: `{account UUID}`, OR an Atlassian Account ID.
required: true
schema:
type: string
- name: workspace
in: path
description: |
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
required: true
schema:
type: string
/user:
get:
tags:
- Users
description: Returns the currently logged in user.
summary: Atlassian Get Current User
responses:
'200':
description: The current user.
content:
application/json:
schema:
$ref: '#/components/schemas/account'
'401':
description: When the request wasn't authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- account
- basic: []
- api_key: []
operationId: atlassianGetCurrentUser
parameters: []
/user/emails:
get:
tags:
- Users
description: >-
Returns all the authenticated user's email addresses. Both<br>confirmed
and unconfirmed.
summary: Atlassian List Email Addresses For Current User
responses:
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- email
- basic: []
- api_key: []
operationId: atlassianListEmailAddressesForCurrentUser
parameters: []
/user/emails/{email}:
get:
tags:
- Users
description: >-
Returns details about a specific one of the authenticated
user's<br>email addresses.<br><br>Details describe whether the address
has been confirmed by the user and<br>whether it is the user's primary
address or not.
summary: Atlassian Get An Email Address For Current User
responses:
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- email
- basic: []
- api_key: []
operationId: atlassianGetAnEmailAddressForCurrentUser
parameters:
- name: email
in: path
description: Email address of the user.
required: true
schema:
type: string
/user/permissions/repositories:
get:
tags:
- Repositories
description: >-
Returns an object for each repository the caller has explicit
access<br>to and their effective permission — the highest level of
permission the<br>caller has. This does not return public repositories
that the user was<br>not granted any specific permission in, and does
not distinguish between<br>explicit and implicit
privileges.<br><br>Permissions can be:<br><br>* `admin`<br>*
`write`<br>* `read`<br><br>Results may be further [filtered or
sorted](/cloud/bitbucket/rest/intro/#filtering) by<br>repository or
permission by adding the following query string<br>parameters:<br><br>*
`q=repository.name="geordi"` or `q=permission>"read"`<br>*
`sort=repository.name`<br><br>Note that the query parameter values need
to be URL escaped so that `=`<br>would become `%3D`.
summary: Atlassian List Repository Permissions For A User
responses:
'200':
description: >-
Repository permissions for the repositories a caller has explicit
access to.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_repository_permissions'
examples:
response:
value:
pagelen: 10
values:
- type: repository_permission
user:
type: user
nickname: evzijst
display_name: Erik van Zijst
uuid: '{d301aafa-d676-4ee0-88be-962be7417567}'
repository:
type: repository
name: geordi
full_name: bitbucket/geordi
uuid: '{85d08b4e-571d-44e9-a507-fa476535aa98}'
permission: admin
page: 1
size: 1
parameters:
- name: q
in: query
description: |2-
Query string to narrow down the response as per
[filtering and sorting](/cloud/bitbucket/rest/intro/#filtering).
required: false
schema:
type: string
- name: sort
in: query
description: |2-
Name of a response property sort the result by as per
[filtering and sorting](/cloud/bitbucket/rest/intro/#filtering).
required: false
schema:
type: string
security:
- oauth2:
- account
- repository
- basic: []
- api_key: []
operationId: atlassianListRepositoryPermissionsForAUser
parameters: []
/user/permissions/workspaces:
get:
tags:
- Workspaces
description: >-
Returns an object for each workspace the caller is a member of,
and<br>their effective role - the highest level of privilege the caller
has.<br>If a user is a member of multiple groups with distinct roles,
only the<br>highest level is returned.<br><br>Permissions can
be:<br><br>* `owner`<br>* `collaborator`<br>* `member`<br><br>**The
`collaborator` role is being removed from the Bitbucket Cloud API. For
more information,<br>see the [deprecation
announcement](/cloud/bitbucket/deprecation-notice-collaborator-role/).**<br><br>**When
you move your administration from Bitbucket Cloud to
admin.atlassian.com, the following fields on<br>`workspace_membership`
will no longer be present: `last_accessed` and `added_on`. See
the<br>[deprecation
announcement](/cloud/bitbucket/announcement-breaking-change-workspace-membership/).**<br><br>Results
may be further [filtered or
sorted](/cloud/bitbucket/rest/intro/#filtering) by<br>workspace or
permission by adding the following query string parameters:<br><br>*
`q=workspace.slug="bbworkspace1"` or `q=permission="owner"`<br>*
`sort=workspace.slug`<br><br>Note that the query parameter values need
to be URL escaped so that `=`<br>would become `%3D`.
summary: Atlassian List Workspaces For The Current User
responses:
'200':
description: All of the workspace memberships for the authenticated user.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_workspace_memberships'
examples:
response:
value:
pagelen: 10
page: 1
size: 1
values:
- type: workspace_membership
permission: owner
last_accessed: '2019-03-07T12:35:02.900024+00:00'
added_on: '2018-10-11T17:42:02.961424+00:00'
user:
type: user
uuid: '{470c176d-3574-44ea-bb41-89e8638bcca4}'
nickname: evzijst
display_name: Erik van Zijst
workspace:
type: workspace
uuid: '{a15fb181-db1f-48f7-b41f-e1eff06929d6}'
slug: bbworkspace1
name: Atlassian Bitbucket
'401':
description: The request wasn't authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
parameters:
- name: q
in: query
description: >2-
Query string to narrow down the response. See
[filtering and sorting](/cloud/bitbucket/rest/intro/#filtering) for
details.
required: false
schema:
type: string
- name: sort
in: query
description: >2
Name of a response property to sort results. See
[filtering and
sorting](/cloud/bitbucket/rest/intro/#sorting-query-results)
for details.
required: false
schema:
type: string
security:
- oauth2:
- account
- basic: []
- api_key: []
operationId: atlassianListWorkspacesForTheCurrentUser
parameters: []
/users/{selected_user}:
get:
tags:
- Users
description: >-
Gets the public information associated with a user account.<br><br>If
the user's profile is private, `location`, `website` and<br>`created_on`
elements are omitted.<br><br>Note that the user object returned by this
operation is changing significantly, due to privacy changes.<br>See the
[announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-changes-gdpr/#changes-to-bitbucket-user-objects)
for details.
summary: Atlassian Get A User
responses:
'200':
description: The user object
content:
application/json:
schema:
$ref: '#/components/schemas/account'
'404':
description: >-
If no user exists for the specified UUID, or if the specified
account is a team account, not a personal account.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2: []
- basic: []
- api_key: []
operationId: atlassianGetAUser
parameters:
- name: selected_user
in: path
description: |
This can either be an Atlassian Account ID OR the UUID of the account,
surrounded by curly-braces, for example: `{account UUID}`.
required: true
schema:
type: string
/users/{selected_user}/pipelines_config/variables:
get:
tags:
- Pipelines
deprecated: true
summary: Atlassian List Variables For A User
description: >-
Find user 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: atlassianGetpipelinevariablesforuser
parameters:
- name: selected_user
description: >-
Either the UUID of the account surrounded by curly-braces, for
example `{account UUID}`, OR an Atlassian Account ID.
required: true
in: path
schema:
type: string
responses:
'200':
description: The found user 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 a user 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: atlassianCreatepipelinevariableforuser
parameters:
- name: selected_user
description: >-
Either the UUID of the account surrounded by curly-braces, for
example `{account UUID}`, OR an Atlassian Account ID.
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: []
/users/{selected_user}/pipelines_config/variables/{variable_uuid}:
get:
tags:
- Pipelines
deprecated: true
summary: Atlassian Get A Variable For A User
description: >-
Retrieve a user 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: atlassianGetpipelinevariableforuser
parameters:
- name: selected_user
description: >-
Either the UUID of the account surrounded by curly-braces, for
example `{account UUID}`, OR an Atlassian Account ID.
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 User
description: >-
Update a user 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: atlassianUpdatepipelinevariableforuser
parameters:
- name: selected_user
description: >-
Either the UUID of the account surrounded by curly-braces, for
example `{account UUID}`, OR an Atlassian Account ID.
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 User
description: >-
Delete 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: atlassianDeletepipelinevariableforuser
parameters:
- name: selected_user
description: >-
Either the UUID of the account surrounded by curly-braces, for
example `{account UUID}`, OR an Atlassian Account ID.
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: []
/users/{selected_user}/properties/{app_key}/{property_name}:
put:
responses:
'204':
description: An empty response.
operationId: atlassianUpdateuserhostedpropertyvalue
summary: Atlassian Update A User Application Property
description: >-
Update an [application
property](/cloud/bitbucket/application-properties/) value stored against
a user.
parameters:
- required: true
in: path
name: selected_user
description: >-
Either the UUID of the account surrounded by curly-braces, for
example `{account UUID}`, OR an Atlassian Account ID.
schema:
type: string
- required: true
in: path
name: app_key
description: The key of the Connect app.
schema:
type: string
- required: true
in: path
name: property_name
description: The name of the property.
schema:
type: string
requestBody:
$ref: '#/components/requestBodies/application_property'
tags:
- Properties
security:
- oauth2: []
- basic: []
- api_key: []
delete:
responses:
'204':
description: An empty response.
operationId: atlassianDeleteuserhostedpropertyvalue
summary: Atlassian Delete A User Application Property
description: >-
Delete an [application
property](/cloud/bitbucket/application-properties/) value stored against
a user.
parameters:
- required: true
in: path
name: selected_user
description: >-
Either the UUID of the account surrounded by curly-braces, for
example `{account UUID}`, OR an Atlassian Account ID.
schema:
type: string
- required: true
in: path
name: app_key
description: The key of the Connect app.
schema:
type: string
- required: true
in: path
name: property_name
description: The name of the property.
schema:
type: string
tags:
- Properties
security:
- oauth2: []
- basic: []
- api_key: []
get:
responses:
'200':
description: The value of the property.
content:
application/json:
schema:
$ref: '#/components/schemas/application_property'
operationId: atlassianRetrieveuserhostedpropertyvalue
summary: Atlassian Get A User Application Property
description: >-
Retrieve an [application
property](/cloud/bitbucket/application-properties/) value stored against
a user.
parameters:
- required: true
in: path
name: selected_user
description: >-
Either the UUID of the account surrounded by curly-braces, for
examp
# --- truncated at 32 KB (194 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-user-openapi-original.yml