OAuth with Bitbucket

Bitbucket is Atlassian's Git hosting service for teams. It combines repositories and pull requests with Bitbucket Pipelines for CI/CD and close integration with Jira, which makes it a common home for engineering teams that already use Atlassian tools.

How does the integration work?

You can use the Bitbucket OAuth adapter in Appwrite Auth to let users sign in with their Bitbucket Cloud account. This fits developer tools, dashboards, and internal apps whose users already work in Bitbucket, since they can start without creating another password.

Appwrite signs users in through bitbucket.org, reads their profile, and uses the first confirmed email address on the account, which it marks as verified. Appwrite doesn't request extra scopes, so the access comes from the permissions you set on the OAuth consumer. Only Bitbucket Cloud is supported.

How to implement

To implement the Bitbucket OAuth adapter in Appwrite Auth, there are several steps you must complete:

Step 1: Create an OAuth consumer on Bitbucket

Bitbucket issues OAuth credentials through OAuth consumers that belong to a workspace. Open your workspace, select the Settings cog, and choose Workspace settings. Under Apps and features, select OAuth consumers, then Add consumer.

Configure the consumer:

• Name: a name your users recognize on the consent screen.
• Callback URL: Bitbucket requires one for OAuth 2.0 consumers. Temporarily enter https://temporary-endpoint.com/. You'll replace it with the URI from Appwrite in the next step.
• Permissions: allow the consumer to read the account and its email addresses (the account and email scopes). Appwrite needs both to read the user's profile and confirmed email.

Save the consumer, then select its name in the list to reveal the Key and Secret. Save both values for later use.

Step 2: Add Bitbucket OAuth adapter to your Appwrite project

For this step, you must create an account on Appwrite Cloud or self-host Appwrite if you haven't already. In your Appwrite project, head over to the Auth page, open the Settings tab, and click Bitbucket under the OAuth2 Providers section.

Paste the consumer's Key and Secret into the matching fields, turn the provider on, and click Update.

Copy the Redirect URI shown in the form. On Appwrite Cloud it looks like https://<REGION>.cloud.appwrite.io/v1/account/sessions/oauth2/callback/bitbucket/<PROJECT_ID>, but always copy the exact value from the Console. Edit the OAuth consumer on Bitbucket and replace the temporary Callback URL with it.

Step 3: Test the provider

Start a session from your app with the OAuthProvider.Bitbucket value. With the Web SDK:

import { Client, Account, OAuthProvider } from 'appwrite';

const client = new Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>');

const account = new Account(client);

account.createOAuth2Session({
    provider: OAuthProvider.Bitbucket,
    success: 'https://example.com/success',
    failure: 'https://example.com/failed',
});

Add your app's domain as a web platform in your Appwrite project so Appwrite accepts the success and failure URLs. Follow the OAuth 2 login flow for other platforms and for server-side sign-in.

Read more about Bitbucket and Appwrite Auth

If you would like to learn more about Bitbucket and Appwrite Auth, we have some resources that you should visit: