Possible Bug Recently Introduced: Retrieving labels?

[mazzarito]

I believe this change:

34f36ef

Or another recent change modified the way labels are retrieved after shipment creation- namely it seems to require authorization now and this wasn't the case before.

Is this documented somewhere? It also seems like its just broken: either with HTTP basic auth or when I request a label /v1/shipments/:id/label.pdf I get the error: Access token required. Use /api/tokens to generate one.

I can successfully perform the same request and retrieve the same shipment at /v1/shipments/:id no problem with the same credentials I'm trying to get the label with.

Maybe I'm missing something- will update if I figure something out!

Thanks!

[mazzarito]

Okay I was missing something, seems /api/tokens is just missing from the docs hosted here: https://docs.karrio.io/reference

So thats what was throwing me off. I understand the thing now, I'm pretty sure DRF doesn't have a convention for a resource access token route and I was getting thrown off that /api/token = normal auth and /api/tokens = resource access token. Coming back with fresh eyes I realized this mistake.

Anyway this makes sense now :)

Great job on all the work you've done @danh91 - I've noticed stability and usability have come a long way in the past year or so.

[danh91]

Hi @mazzarito ,

I updated the docs to address this point. Please check

https://www.karrio.io/docs/developing/shipping-integration

section #Token-Based Document Access

There have been multiple complaints that the label shouldn't be accessible publicly to anyone with the link when the server is not in a private network. So we introduced this new limited scope token strictly for document downloads, so the dashboard used that as well.

However, for integrations, the last 2025.5.4 release that just went out returns the document in base64 along with the shipment when you buy the label

check https://www.karrio.io/docs/developing/shipping-integration section #Shipping Documents Access Patterns

[danh91]

@mazzarito

For "security" reasons, the document downloads APIs are not published along with the public OpenAPI so we had to document it instead somewhere. Hopefully, we will find a better way to document it.

Let me know what you think.

[mazzarito]

Hey @danh91 Thanks for your reply!

EDIT Just saw this: However, for integrations, the last 2025.5.4 release that just went out returns the document in base64 along with the shipment when you buy the label OKAY now we're talking, I will look for this, as it was my other suggestion, I didn't see it in the response but maybe I missed it.

---

I didn't realize there was a separate docs site hosted at /docs I guess but:

That makes sense! I was almost certain I was just missing something, I will keep that bookmark as well, and yes I can see how for a lot of use cases this would be prickly :)

Part of me wonders if just including a public_label_url with a token included in the shipping creation response alongside label_url wouldn't just be simpler.

That way the ability to: "create label, retrieve label" doesn't require an extra token/request.

I'm not 100% certain of the security implications of that, but it seems like if someone has permission to create a label they should have permission to get the link to pull it down.

I guess it boils down to: the old paradigm was handy for anybody that didn't publicly expose the URLs, this one is great for people that do, but surely both use cases can be served here.

Anyway it's not a huge inconvenience either way. Overall I do think having /api/token and /api/tokens is a bit close from an api design standpoint but maybe there's a reason for that.

Thanks again for the reply, have a great day!