Atlassian Bitbucket User Management API Guide

Auth method: OAuth 2.0 (Authorization Code, Client Credentials, Implicit grants); also App Passwords (HTTP Basic) and Repository/Project/Workspace Access Tokens (Bearer)

Setup steps

1. Go to Workspace Settings > Apps and features > OAuth consumers.
2. Click 'Add consumer', provide a name and a Callback URL (required for OAuth 2.0).
3. Select the required permission scopes (e.g., 'account', 'repository:admin').
4. Save; Bitbucket generates a Client Key and Client Secret.
5. Exchange the authorization code for an access token via POST https://bitbucket.org/site/oauth2/access_token with grant_type=authorization_code.
6. Use the returned Bearer token in the Authorization header for all API requests.
7. Alternatively, create an App Password under Personal Settings > App passwords and use HTTP Basic Auth (email:app_password).
8. For server-to-server use, create a Workspace/Repository Access Token under Workspace Settings > Access tokens.

Required scopes

Get authenticated user (self)

• Method: GET
• URL: https://api.bitbucket.org/2.0/user
• Watch out for: Requires 'account' OAuth 2.0 scope. This is the only endpoint that still returns the legacy 'username' field.

Request example

curl --request GET \
  --url 'https://api.bitbucket.org/2.0/user' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Response example

{
  "type": "user",
  "uuid": "{abc123}",
  "account_id": "557058:abc",
  "display_name": "Jane Doe",
  "nickname": "janedoe",
  "created_on": "2020-01-01T00:00:00Z"
}

Get a specific user by account_id or uuid

• Method: GET
• URL: https://api.bitbucket.org/2.0/users/{selected_user}
• Watch out for: Returns only public profile data. Username-based URLs are deprecated; use account_id or uuid. User privacy settings may limit display_name and avatar visibility.

Request example

curl --request GET \
  --url 'https://api.bitbucket.org/2.0/users/557058:abc' \
  --header 'Authorization: Bearer <access_token>'

Response example

{
  "type": "user",
  "uuid": "{abc123}",
  "account_id": "557058:abc",
  "display_name": "Jane Doe",
  "nickname": "janedoe"
}

List authenticated user's email addresses

• Method: GET
• URL: https://api.bitbucket.org/2.0/user/emails
• Watch out for: Requires 'email' or 'account' scope. Returns both confirmed and unconfirmed addresses for the authenticated user only.

Request example

curl --request GET \
  --url 'https://api.bitbucket.org/2.0/user/emails' \
  --header 'Authorization: Bearer <access_token>'

Response example

{
  "pagelen": 10,
  "values": [
    {"type": "email", "email": "jane@example.com",
     "is_primary": true, "is_confirmed": true}
  ]
}

List workspace members

• Method: GET
• URL: https://api.bitbucket.org/2.0/workspaces/{workspace}/members
• Watch out for: Requires workspace membership to call. Does not support adding or removing members via this endpoint; membership is managed through Atlassian Admin or SCIM.

Request example

curl --request GET \
  --url 'https://api.bitbucket.org/2.0/workspaces/myworkspace/members' \
  --header 'Authorization: Bearer <access_token>'

Response example

{
  "pagelen": 10,
  "values": [
    {"type": "workspace_membership",
     "user": {"type": "user", "uuid": "{abc}"},
     "workspace": {"type": "workspace"}}
  ]
}

Get a specific workspace member

• Method: GET
• URL: https://api.bitbucket.org/2.0/workspaces/{workspace}/members/{member}
• Watch out for: Member must be identified by account_id or uuid, not username.

Request example

curl --request GET \
  --url 'https://api.bitbucket.org/2.0/workspaces/myworkspace/members/557058:abc' \
  --header 'Authorization: Bearer <access_token>'

Response example

{
  "type": "workspace_membership",
  "user": {"type": "user", "uuid": "{abc}"},
  "workspace": {"type": "workspace", "slug": "myworkspace"}
}

List repository-level user permissions

• Method: GET
• URL: https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/permissions-config/users
• Watch out for: Requires 'repository:admin' scope and repository admin permission. Only returns explicit (direct) permissions, not inherited group permissions.

Request example

curl --request GET \
  --url 'https://api.bitbucket.org/2.0/repositories/myws/myrepo/permissions-config/users' \
  --header 'Authorization: Bearer <access_token>'

Response example

{
  "pagelen": 10,
  "values": [
    {"type": "repository_user_permission",
     "permission": "write",
     "user": {"type": "user", "uuid": "{abc}"}}
  ]
}

Set/update a user's repository permission

• Method: PUT
• URL: https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/permissions-config/users/{selected_user}
• Watch out for: Requires 'repository:admin' scope. Valid permission values: 'read', 'write', 'admin'. Cannot grant permissions higher than the caller's own.

Request example

curl --request PUT \
  --url 'https://api.bitbucket.org/2.0/repositories/myws/myrepo/permissions-config/users/557058:abc' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{"permission": "write"}'

Response example

{
  "type": "repository_user_permission",
  "permission": "write",
  "user": {"type": "user", "uuid": "{abc}"}
}

Remove a user's explicit repository permission

• Method: DELETE
• URL: https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/permissions-config/users/{selected_user}
• Watch out for: Only removes the explicit direct permission. User may still have access via group membership. Requires 'repository:admin' scope.

Request example

curl --request DELETE \
  --url 'https://api.bitbucket.org/2.0/repositories/myws/myrepo/permissions-config/users/557058:abc' \
  --header 'Authorization: Bearer <access_token>'

Response example

HTTP 204 No Content

• Rate limits: Rate limits are applied per rolling one-hour window. Authenticated requests are measured per user ID; unauthenticated requests per IP address. A 429 response is returned when the limit is exceeded. Scaled rate limits apply to the 'api resource group' (most /2.0/repositories/* endpoints) for requests made via Access Tokens or Forge asApp, adding 10 requests/hour per paid workspace seat, capped at 10,000 requests/hour.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: Rate limit headers returned for scaled endpoints: X-RateLimit-Limit (total permitted/hour), X-RateLimit-Resource (endpoint group), X-RateLimit-NearLimit (boolean, true when <20% remaining). No Retry-After header is documented; back-off and retry after waiting is recommended. Resource and rate limits are not part of the stable API contract and may change dynamically.
• Pagination method: offset
• Default page size: 10
• Max page size: 100
• Pagination pointer: pagelen (page size), page (page number)

• Webhooks available: Yes
• Webhook notes: Bitbucket Cloud supports repository-scoped and workspace-scoped webhooks. After creation, Bitbucket sends an HTTP POST payload to the configured URL whenever a subscribed event occurs. Webhooks are not rate-limited unlike API requests. The 'webhook' scope is required to create or manage webhook subscriptions.
• Alternative event strategy: No native user lifecycle webhook events (e.g., user added/removed from workspace) exist in Bitbucket Cloud. For user provisioning events, use the Atlassian SCIM API or poll /workspaces/{workspace}/members.
• Webhook events: repo:push, repo:fork, repo:updated, repo:commit_comment_created, repo:commit_status_created, repo:commit_status_updated, pullrequest:created, pullrequest:updated, pullrequest:approved, pullrequest:unapproved, pullrequest:fulfilled, pullrequest:rejected, pullrequest:comment_created, pullrequest:comment_updated, pullrequest:comment_deleted, issue:created, issue:updated, issue:comment_created

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Atlassian Guard Standard subscription (separate add-on, ~$3–4/user/month billed per managed user across the Atlassian organization). SSO must be configured before enabling SCIM.

• Endpoint: https://api.atlassian.com/scim/directory/{directoryId}/Users

• Supported operations: GET /scim/directory/{directoryId}/Users - list users (paginated via startIndex, default 100/page), POST /scim/directory/{directoryId}/Users - create/provision a user, GET /scim/directory/{directoryId}/Users/{userId} - get a single user, PUT /scim/directory/{directoryId}/Users/{userId} - full replace of user attributes, PATCH /scim/directory/{directoryId}/Users/{userId} - partial update (e.g., set active=false to deactivate), DELETE /scim/directory/{directoryId}/Users/{userId} - deprovision/delete a user

Limitations:

• Group sync (SCIM Groups) is NOT available for Bitbucket - only user account provisioning is supported. Group sync is available for Jira and Confluence only.
• SCIM only provisions Atlassian accounts; it does not assign repository-level permissions in Bitbucket. Repository access must be managed manually or via the Bitbucket permissions API.
• SCIM API keys expire after one year (enforced from January 2025); annual rotation is required.
• The directoryId is generated at setup time in admin.atlassian.com and is not shown again after initial configuration - store it securely.
• Deactivating a SCIM-provisioned user deactivates them across all Atlassian products in the organization, not just Bitbucket.
• Updating a SCIM-provisioned user's email must be done via the SCIM API, not the Bitbucket user management API.
• Batch group membership syncs above 10,000 users will suspend subsequent directory syncs.
• SSO (SAML) must be configured and domain verified before SCIM provisioning can be enabled.

Three primary automation scenarios are well-supported by the API, each with explicit constraints to plan around.

Looking up workspace members and permissions: Use GET /workspaces/{workspace}/members (paginated, pagelen max 100) to list members, then GET /repositories/{workspace}/{repo_slug}/permissions-config/users to retrieve explicit repo-level permissions. Note that workspace member listing does not return email addresses - email is only available for the authenticated user via GET /user/emails. Always reference users by account_id or uuid; username-based paths are deprecated since April 2019.

Granting or updating repository permissions: PUT /repositories/{workspace}/{repo_slug}/permissions-config/users/{account_id} with a body of {"permission": "read|write|admin"} requires the repository:admin scope. The caller cannot grant a permission level higher than their own. This sets only the explicit direct permission; group-inherited access is managed separately and is not visible from this endpoint.

Provisioning a new user via SCIM: POST to api.atlassian.com/scim/directory/{directoryId}/Users creates the Atlassian account. SCIM alone does not grant Bitbucket product access or assign any repository permissions - a separate group assignment in Atlassian Admin and a subsequent Bitbucket permissions API call are both required. SCIM API keys expire after one year and must be rotated manually. Group sync via SCIM is not supported for Bitbucket; it is available only for Jira and Confluence.

Look up a workspace member's profile and permissions

1. Authenticate via OAuth 2.0 (Authorization Code) or App Password with 'account' and 'repository' scopes.
2. GET https://api.bitbucket.org/2.0/workspaces/{workspace}/members to list all members; paginate using ?page=N&pagelen=50.
3. Identify the target user's account_id or uuid from the response.
4. GET https://api.bitbucket.org/2.0/users/{account_id} to retrieve the user's public profile.
5. GET https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/permissions-config/users to list explicit repo permissions; filter for the target user.

Watch out for: Workspace member listing does not include email addresses. Email is only available for the authenticated user via GET /user/emails. User privacy settings may hide display_name.

Grant a user write access to a repository

1. Authenticate with an account that has repository admin rights; use 'repository:admin' scope.
2. Resolve the target user's account_id (e.g., from GET /workspaces/{workspace}/members).
3. PUT https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/permissions-config/users/{account_id} with body {"permission": "write"}.
4. Verify the response returns the updated permission object (HTTP 200).

Watch out for: You cannot grant a permission level higher than your own. This sets an explicit direct permission; the user may already have access via group membership which is managed separately.

Provision a new user via SCIM and verify Bitbucket access

1. Ensure Atlassian Guard Standard is active and SSO is configured; retrieve the directoryId and SCIM API key from admin.atlassian.com > Security > Identity providers > Set up user provisioning.
2. POST https://api.atlassian.com/scim/directory/{directoryId}/Users with SCIM 2.0 user payload (userName, name.givenName, name.familyName, emails[primary]).
3. Confirm the user appears in admin.atlassian.com under Managed Accounts.
4. Assign the user to a Bitbucket-access group in Atlassian Admin to grant product access (SCIM alone does not grant Bitbucket access).
5. Use the Bitbucket permissions API (PUT /repositories/.../permissions-config/users/{account_id}) to assign repository-level permissions as needed.

Watch out for: SCIM creates the Atlassian account but does NOT assign Bitbucket repository permissions or group memberships within Bitbucket. Group sync via SCIM is not supported for Bitbucket. SCIM API keys expire annually and must be rotated manually.

The most significant API trap is the split between account lifecycle and permission management. SCIM handles account creation and deactivation at the Atlassian org level, but it has no mechanism to assign or sync Bitbucket repository or project permissions.

Any automation that stops at SCIM provisioning leaves users with an Atlassian account but no usable Bitbucket access - or, on offboarding, deactivates the account org-wide across all Atlassian products, not just Bitbucket.

Rate limits are applied per rolling one-hour window: 1,000 requests/hour for authenticated standard endpoints, scaling to a maximum of 10,000/hour for Access Token or Forge asApp calls against the api resource group (1,000 + 10 × paid seats). No Retry-After header is returned on 429 responses; implement exponential backoff.

Rate limit thresholds are not part of the stable API contract and may change dynamically.

Additional sharp edges: the directoryId generated during SCIM setup in admin.atlassian.com is not displayed again after initial configuration - store it securely at setup time. Access tokens (workspace/project/repository) appear as a bot user in logs and cannot call the /user (self) endpoint. The /user/workspaces endpoint is deprecated and scheduled for removal by end of 2025.