Bitbucket signs users in with their Atlassian-hosted Bitbucket account. It belongs on developer tools whose users host code there rather than on GitHub or GitLab.

## Copy the redirect URI

In the [Authdog console](https://console.authdog.com), select the project and environment, open **Authentication > Providers**, find **Bitbucket**, and click **Enable**. Copy the redirect URI shown in the form:

```url
https://identity.authdog.com/api/v1/callback/<connectionId>
```

## Create the OAuth consumer

1. Open your workspace settings on [Bitbucket](https://bitbucket.org/) and select **OAuth consumers**.
2. Select **Add consumer**.
3. Name the consumer and set the **Callback URL** to the redirect URI from Authdog.
4. Grant the **Account: Read** permission — enough to read the profile.
5. Save, then copy the **Key** and **Secret**.

## Configure Authdog

| Field | Value |
| --- | --- |
| **Client ID** | The client identifier from the provider |
| **Client Secret** | The client secret from the provider |

Save, then toggle the connection **active**.

## What Bitbucket returns

Authdog requests the provider's default scopes and reads the profile from `https://bitbucket.org/api/2.0/user`.

The user endpoint returns the account UUID, username, display name, and avatar. Authdog links on the UUID, which survives username changes.

Bitbucket keeps email addresses on a separate endpoint and hides them unless the account permits it, so expect users with no email on their Authdog record.

## Test it

1. Open your environment's hosted sign-in page, or link to `https://identity.authdog.com/api/v1/signin/<connectionId>`.
2. Select the Bitbucket button and complete the flow.
3. Confirm the user appears under **Users** in the console with a Bitbucket identity linked.

## Troubleshooting

| Symptom | Cause |
| --- | --- |
| `invalid_grant` | The consumer's callback URL differs from the one used at sign-in |
| Empty email | The Bitbucket account has no public email — expected behaviour |
| Redirect or callback URL error | The URI registered with the provider does not match Authdog's exactly |
| Works in one environment only | Each environment has its own `connectionId`, and so its own redirect URI to register |

## Related

| Read | To learn how to |
| --- | --- |
| [Connectors](/docs/connectors) | Set up any other social provider |
| [GitHub](/docs/connectors/github) | Offer the developer identity most users already have |