Context
bkt auth login currently uses API tokens (Cloud) and PATs (DC) with copy-paste. Both Bitbucket Cloud and Data Center support OAuth 2.0 for API access, which would enable a browser-based login flow similar to gh auth login --web.
This came up during review of #133 and triage of #121 — the auth UX has room to improve.
What Bitbucket supports
|
Cloud |
DC |
| Auth Code Grant (3LO) |
Yes |
Yes |
| PKCE |
No |
Yes |
| Device Flow (RFC 8628) |
No |
No |
| Localhost redirect (RFC 8252) |
Yes |
Likely (admin-controlled) |
Sources:
What gh does
gh auth login --web uses OAuth device flow (RFC 8628), falling back to auth code + localhost server. Bitbucket doesn't support device flow on either platform, so bkt would use the auth-code + localhost-server pattern.
Rough implementation sketch
Cloud:
- Register an OAuth consumer in a bkt-owned workspace (scopes:
repository, pullrequest, account, etc.)
bkt auth login --web starts a temporary localhost HTTP server, opens browser to Bitbucket's authorize URL- User grants access, Bitbucket redirects to localhost with auth code
- Exchange code for access_token + refresh_token (2h TTL, auto-refresh)
- Store tokens in config, auto-refresh on expiry
Caveat: Cloud lacks PKCE, so the client_secret ships with the binary. Same trade-off gh makes.
DC:
Same flow but with PKCE (no embedded secret needed). Endpoints at /rest/oauth2/latest/.... Requires admin to set up an Application Link.
Trade-offs vs current auth
- Better UX: one-click browser flow vs copy-paste tokens
- Better security: short-lived tokens (2h) with auto-refresh vs long-lived PATs
- More setup: OAuth consumer registration (Cloud), Application Links (DC)
- Embedded secret: Cloud requires client_secret in binary (no PKCE)
Scope
This would add a --web / --oauth flow alongside the existing token-based login, not replace it. Token-based auth remains the default for headless/CI use cases (especially with BKT_TOKEN).
Not blocking anything — just capturing the research while it's fresh.
Context
bkt auth logincurrently uses API tokens (Cloud) and PATs (DC) with copy-paste. Both Bitbucket Cloud and Data Center support OAuth 2.0 for API access, which would enable a browser-based login flow similar togh auth login --web.This came up during review of #133 and triage of #121 — the auth UX has room to improve.
What Bitbucket supports
Sources:
What
ghdoesgh auth login --webuses OAuth device flow (RFC 8628), falling back to auth code + localhost server. Bitbucket doesn't support device flow on either platform, so bkt would use the auth-code + localhost-server pattern.Rough implementation sketch
Cloud:
repository,pullrequest,account, etc.)bkt auth login --webstarts a temporary localhost HTTP server, opens browser to Bitbucket's authorize URLCaveat: Cloud lacks PKCE, so the client_secret ships with the binary. Same trade-off
ghmakes.DC:
Same flow but with PKCE (no embedded secret needed). Endpoints at
/rest/oauth2/latest/.... Requires admin to set up an Application Link.Trade-offs vs current auth
Scope
This would add a
--web/--oauthflow alongside the existing token-based login, not replace it. Token-based auth remains the default for headless/CI use cases (especially withBKT_TOKEN).Not blocking anything — just capturing the research while it's fresh.