Community
Q&A
Bitbucket
Questions
Does repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/conflicts support ApiToken?

Does repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/conflicts support ApiToken?

Hello,

First of all, thank you for your efforts.

I am currently using Bitbucket API Tokens, and I noticed a potential inconsistency with the new conflict detection APIs.

The endpoint:

/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/conflicts

explicitly states that the following scope is supported:

Forge app and API Token scopes required:

read:pullrequest:bitbucket

However, this endpoint redirects to:

/repositories/{workspace}/{repo_slug}/file-conflicts/{spec}

and the redirected endpoint appears not to support API Token authentication. As a result, I receive the following error:

{ "type": "error", "error": { "message": "This resource does not support authentication using the provided token" } }

For comparison, the standard pull request endpoint:

/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}

works correctly with the same API Token and has the same documented requirement of "Forge app and API Token scopes required".

Could you please investigate whether this is an issue with the implementation or the documentation?

We are currently relying on conflict detection functionality, and we would appreciate clarification as soon as possible, especially given the upcoming deprecation of the merge=true parameter scheduled for September 4, 2026.

Thank you in advance for your assistance. We look forward to your feedback.

1 answer

0 votes

Hi @roustommx, the spec annotates those two endpoints inconsistently, so one of the annotations has to be wrong.

In api.bitbucket.org/swagger.json, 271 of the 298 operations carry an x-atlassian-auth-types entry naming api-token. GET /repositories/{workspace}/{repo_slug}/file-conflicts/{spec}, the target of your 302, carries no such entry at all. The rendered docs say the same thing quietly. Every operation on the Commits page prints a Forge app and API Token scopes line except that one. The scope moves across the hop too, pullrequest going in and repository at the far end, and you can watch it happen. Call /conflicts without -L and the 302 comes back carrying x-accepted-oauth-scopes: pullrequest.

If merge=true is what you're calling now, that's GET /repositories/{ws}/{repo}/diff/{spec}. It carries api-token, on read:repository:bitbucket. Its classic security block is the one file-conflicts carries, repository in both. So whatever token you already use for diff is the one to aim at file-conflicts, and that costs you a request.

Take the URL off the Location header instead of building the spec yourself. The 302 hands you Bitbucket's own revspec, and it doesn't look like the sha..sha form the docs give for that path parameter. When I ran it against a public repo the Location came back as workspace/repo:sha%0Dsha. Copy it, re-issue it with the other token. Conflicts come back, you're unblocked and the target is missing its annotation. Same sentence again, and no scope is going to move it.

Someone already got that second outcome. github.com/solrevdev/solrevdev.bbx swept the API with a real token on 6 August and logged your exact message against file-conflicts, as a 403, with a note that no scope fixes it. Their repo, and I hold no Bitbucket token to check it against, so treat it as a strong hint and go get your own result.

Nothing is filed in BCLOUD. The only file-conflicts hit there is a 2013 issue about something else. Put both spec entries side by side in the ticket and paste the response verbatim, status line included. You didn't say what code came back with that body. That part carries the weight. A 403 says the credential authenticated and the resource turned its type away, and a 401 would be a different bug report.

You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.

Comment

Thanks for your reply! the status code is actually 403 and not 401
PR conflicts API.png

You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.

Comment

Thanks for the detailed investigation and suggestions.

One point I'd like to clarify: is there any plan or willingness from the Bitbucket team to support API Tokens for the /file-conflicts/{spec} endpoint?

In our case, we rely exclusively on Bitbucket API Tokens for authentication and do not currently use OAuth-based authentication flows. As a result, using a different credential type for the redirected endpoint is not a practical workaround for us.

Given that /pullrequests/{pull_request_id}/conflicts explicitly documents API Token support, we expected the conflict detection workflow to be fully usable with API Tokens end-to-end.

Could you please confirm whether:

Support for API Tokens on /file-conflicts/{spec} is planned or being considered?
The current behavior is intentional, with API Tokens not supported on the redirected endpoint?
Or if this is considered a bug or documentation issue that will be addressed?

This would help us understand whether we should expect a future fix or start evaluating alternative approaches before the deprecation of the merge=true parameter on September 4, 2026.

Thanks again for your help.

You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.

Comment

On the three questions, I can't answer them and neither can anyone outside the Bitbucket team. Whether api-token support on that path is planned, deliberate, or a defect is theirs to state.

What I can tell you is that the gap is unchanged tonight. I pulled api.bitbucket.org/swagger.json again. file-conflicts/{spec} still carries no x-atlassian-auth-types entry at all, while the /conflicts entry point and /diff/{spec} both carry forge-oauth2 and api-token. The counts moved since I last looked, 269 of 296 operations now against 271 of 298 then, so the spec has changed in between and the omission came through it untouched. An absent entry in a generated spec reads to me like something that was not added rather than something that was decided, though that is my inference and not a statement of intent.

Your 403 settles the other half. The credential authenticated and the resource refused the token type, which is the sentence to put in the ticket.

Nothing is filed in BCLOUD. I checked again tonight, and the closest hits are a 2017 diff 401 and some 2016 merge-conflict UI issues. Until a ticket exists there is nobody on the hook to answer you.

You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.

Comment

Suggest an answer

Was this helpful?

Thanks!

Bitbucket

DEPLOYMENT TYPE

CLOUD

PERMISSIONS LEVEL

Product Admin Site Admin

Forums

Q&A

Community resources

Support

Top groups

Community resources

Support

Learn

Community resources

Support

Events

Community resources

Support

Does repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/conflicts support ApiToken?

1 answer

Suggest an answer

Was this helpful?

Thanks!

DEPLOYMENT TYPE

PERMISSIONS LEVEL

TAGS

Atlassian Community Events