How It Started
A colleague from our integration team pinged me one afternoon. They had an x-auth-token for our Sitecore Content Hub QA environment and were trying to upload assets programmatically. Every time they called POST /api/v2.0/upload, they got this:
{
"Message": "You don't have the 'Read' permission to perform this action."
}
HTTP status: 401.
They were a bit confused, the error mentioned "Read" but they were doing a POST (a write operation). They also started wondering if maybe they were supposed to pass a user ID somewhere in the request, or if the token itself wasn't enough.
First, Clearing Up the x-auth-token Confusion
Before debugging permissions, I wanted to clarify one thing the team member was unsure about: how x-auth-token actually works.
The x-auth-token value is generated by calling POST /api/authenticate with a username + password. Once you have that token, only the token header goes into every subsequent request, there's no user ID or username to pass separately. The token itself carries the user identity.
So if you have the token for user integrationapiteam.ch, every request with that token is automatically made as that user. Nothing else is needed for identity.
That was one confusion cleared. The real question was: why is a valid token getting a 401?
Step 1: Reproduce the Issue
Before jumping to fixes, I wanted to confirm the problem myself. I grabbed my own x-auth-token:
- Logged into the Content Hub instance
- Reused that same x-auth-token in the identical POST /api/v2.0/upload request the integration team was using.
- Pasted it into the same upload request the team was using
And... I also got the 401. Good, reproducible.
Then I tried with my superuser credentials. Same call, different token and this time:
201 Created ✅
That told me everything. The request itself was perfectly valid. The issue was purely about which user was making it. Superusers bypass all policy checks, so they never hit this. Regular integration users do.
Understanding What the Upload API Actually Does
To figure out why the 401 was happening, I needed to understand what POST /api/v2.0/upload actually does under the hood. The Content Hub upload flow is a 3-step process:
Step 1: Request an Upload URL
POST https://ch.instance/api/v2.0/upload
X-Auth-Token: {your-token}
Content-Type: application/json
{
"file_name": "myfile.jpg",
"file_size": 12345,
"action": { "name": "NewAsset" },
"upload_configuration": { "name": "AssetUploadConfiguration" }
}The response gives you:
- Body →
upload_identifier+file_identifier - Location header → the URL to use for Step 2