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

See Downloading code for the archive and clone-URL methods themselves.

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.