Get started with Bitbucket Cloud
New to Bitbucket Cloud? Check out our get started guides for new users.
Using Workspace Access Tokens
Workspace Access Tokens are a premium feature. To learn about the Bitbucket Cloud Premium plan, visit: Bitbucket Cloud Premium.
Workspace Access Tokens are single-purpose access tokens with reduced access (specified during creation) that can be useful for scripting, CI/CD tools, and testing Bitbucket-connected apps during development. Workspace Access Tokens are tied to a workspace, not a user, and are managed by the workspaces' admins.
The following examples show how to use Bitbucket Cloud Workspace Access Tokens with Bitbucket Cloud REST APIs and the Git command line interface (Git CLI).
Using Workspace Access Tokens with Bitbucket APIs
We recommend Bitbucket Cloud integration or app developers use OAuth for user authentication. For information on creating a Bitbucket Cloud integration or app with OAuth support, visit Atlassian Developer - Bitbucket Cloud.
The following example shows how to use a Bitbucket Cloud Workspace Access Token with the curl command as a guide for how to authenticate with Bitbucket Cloud APIs. This example is querying the commits on a Bitbucket repository using the Get Repository API.
To connect to Bitbucket Cloud, send the Workspace Access Token as a bearer token in an HTTP Authorization header. For example:
1
2
3
4
curl --request GET \
--url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repository}' \
--header 'Authorization: Bearer <workspace_access_token>' \
--header 'Accept: application/json'Using Workspace Access Tokens with the Git command line interface
Workspace Access Tokens should be used with the Git command-line interface in programs and scripts that are non-interactive, such as build tools, automation scripts, and CI/CD applications. When using Git daily, we recommend connecting to Bitbucket Cloud using SSH keys or Git Credential Manager to avoid manually entering a Workspace Access Token every time you issue a command that interacts with Bitbucket. For details on setting up SSH keys for Bitbucket, see: Set up SSH keys for Bitbucket Cloud.
To use a Bitbucket Cloud Workspace Access Token with the Git CLI, create a Workspace Access Token with the following permissions:
Repository Read (repository)
Repository Write (repository:write)
You have two options for using a Workspace Access Token with the Git CLI: provide the Workspace Access Token through an interact prompt, or include the Repository Access Token in the URL.
Workspace Access Tokens through the interactive password prompt
This method avoids storing the Workspace Access Token insecurely in the URL. It requires the Workspace Access Token to be input every time Git interacts with Bitbucket Cloud (such as git pull, git push, and git fetch). You will also need to configure the git user for the repository.
To provide the Workspace Access Token through an interactive prompt:
Clone the repository with the following command:
1git clone https://x-token-auth@bitbucket.org/{workspace}/{repository}.gitFor repositories already cloned to the local device, update the remote URL with the following command:
1git remote set-url origin https://x-token-auth@bitbucket.org/{workspace}/{repository}.gitNavigate into the newly cloned repository:
1cd {repository}/Set the git user for the repository, such as:
1git config user.email "{bot_email}"Where {bot_email} is the Workspace Access Token email generated when you created the Workspace Access Token (for example, 52c16467c5f19101ff2061cc@bots.bitbucket.org).
The Workspace Access Token email:
Is not the Workspace Access Token name.
Can be retrieved from the Workspace Access Tokens page on the repository by selecting the name of the Access Token.
Can't send or receive emails and is only used for matching Git operations to the Access Token.
Include the Workspace Access Token in the URL
We recommend not storing the Workspace Access Token insecurely as plain text or permanently as part of the git remote URL. This method is useful if the Workspace Access Token has been stored securely as a 'secret' variable in a build tool.
To use Workspace Access Tokens without an interactive password prompt, you can include the Workspace Access Token in the URL. For example:
Clone the repository with the following command:
1git clone https://x-token-auth:{workspace_access_token}@bitbucket.org/{workspace}/{repository}.gitFor repositories already cloned to the local device, update the remote URL with the following command:
1git remote set-url origin https://x-token-auth:{workspace_access_token}@bitbucket.org/{workspace}/{repository}.gitNavigate into the newly cloned repository:
1cd {repository}/Set the git user for the repository, such as:
1git config user.email "{botid}@bots.bitbucket.org"Where {botid} is the Workspace Access Token id generated when you created the Workspace Access Token. The Workspace Access Token id is not the Repository Access Token name.
Was this helpful?