Bitbucket authentication

Authenticate the Bitbucket Cloud provider with an API token or an access token.

The bitbucket provider from repo-sdk/bitbucket authenticates with an Atlassian API token (HTTP Basic) or a workspace/repo access token (Bearer). Bitbucket Cloud only — there is no baseUrl.

API token auth (recommended)

Provide an Atlassian account email and an API token. The SDK combines them into an HTTP Basic credential.

import { createClient } from 'repo-sdk';
import { bitbucket } from 'repo-sdk/bitbucket';

const client = createClient({
  provider: bitbucket({
    auth: {
      email: process.env.BITBUCKET_EMAIL!,
      apiToken: process.env.BITBUCKET_API_TOKEN!,
    },
  }),
});

Access token auth

Alternatively, provide a workspace or repository access token (or an OAuth token). The SDK sends it as a Bearer credential.

bitbucket({ auth: { accessToken: process.env.BITBUCKET_ACCESS_TOKEN! } });

Scopes

Pick the token scope for what you’ll do. A scoped Atlassian API token — or a workspace/repository access token — needs these; an unscoped Atlassian API token inherits your full account access and needs none.

Atlassian API tokens (granular scopes):

• read:repository:bitbucket — required for discovery, commits, tags, branches, ref search, and archive downloads.
• read:workspace:bitbucket — required to list workspace namespaces.
• read:user:bitbucket — required for users.me (and its email, with includeEmail).
• read:webhook:bitbucket and write:webhook:bitbucket — required to read, and to create/update/delete, webhooks.

Workspace/repository access tokens and OAuth (classic scopes):

• repository — required for discovery, commits, tags, branches, ref search, and clone access.
• account — required to list workspace namespaces and for users.me.
• email — required for the primary email in users.me({ includeEmail: true }).
• webhook — required to read and write webhooks (a single scope grants both).

Archive downloads require an API token

Cloud only

The bitbucket factory takes no baseUrl. Only Bitbucket Cloud (bitbucket.org) is supported; there is no Bitbucket Data Center / Server support. The repo string is workspace/repo_slug.

Expiring tokens

auth: { tokenProvider } mints the bearer token per request, with one forced-refresh retry on 401 — see Expiring tokens for the contract.