-
Type:
Suggestion
-
Resolution: Unresolved
-
Component/s: API Framework - Authentication
Issue summary: When a valid OAuth 2.0 user (3LO) access token is used against api.bitbucket.org/2.0, and the Atlassian account behind the token has no corresponding Bitbucket user, every endpoint returns a generic 401: {}{"type":"error","error":{"message":"Token is invalid, expired, or not supported for this endpoint."{}}}. This message is misleading, since the token is valid and authenticated by Atlassian Identity; the real cause is that the account is not provisioned in Bitbucket. Developers spend significant time debugging token issuance, scopes, and request format before the actual cause is identified.
Steps to reproduce:
- Complete the OAuth 2.0 authorization-code (3LO) flow with a Bitbucket Cloud OAuth client, using an Atlassian account that does not yet have a Bitbucket user.
- Exchange the code at POST https://bitbucket.org/site/oauth2/access_token. Result: 200 with a Bearer access token.
- Call GET https://api.bitbucket.org/2.0/user with Authorization: Bearer <access_token>.
Expected results: A descriptive error (for example 403 with a message indicating the account has no Bitbucket user and a pointer to sign up at bitbucket.org), clearly distinguishing this case from an invalid or expired token.
Actual results: 401 {"type":"error","error":{"message":"Token is invalid, expired, or not supported for this endpoint."}} on all /2.0 endpoints, even though the token is valid and accepted by api.atlassian.com.
Workaround: The user must sign up for a Bitbucket account at bitbucket.org; once the account exists, the 3LO tokens work. There is no way to detect this programmatically from the error response today.